ETSITS129 198-14 V9.0.0 



(2010-01) 



Technical Specification 



Digital ceiiuiar telecommunications system (Phase 2+) 
Universal Mobile Telecommunications System (UMTS) 

LTE 
Open Service Access (OSA) 
Application Programming Interface (API); 
Part 14: Presence and Availability Management (PAM) 

Service Capability Feature (SCF) 
(3GPP TS 29.198-14 version 9.0.0 Release 9) 



33i^ 





U 



3GPP TS 29.1 98-1 4 version 9.0.0 Release 9 1 ETSI TS 1 29 1 98-1 4 V9.0.0 (201 0-01 ) 



Reference 



RTS/TSGC-00291 98-1 4v900 
Keywords 



GSM, LTE, UMTS 



ETSI 

650 Route des Lucioles 
F-06921 Sophia Antipolis Cedex - FRANCE 

Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 1 6 

Siret N ° 348 623 562 0001 7 - NAF 742 C 
Association a but non lucratif enregistree a la 
Sous-Prefecture de Grasse (06) N° 7803/88 



Important notice 



Individual copies of the present document can be downloaded from: 
http://www.etsi.orq 

The present document may be made available in more than one electronic version or in print. In any case of existing or 

perceived difference in contents between such versions, the reference version is the Portable Document Format (PDF). 

In case of dispute, the reference shall be the printing on ETSI printers of the PDF version kept on a specific network drive 

within ETSI Secretariat. 

Users of the present document should be aware that the document may be subject to revision or change of status. 

Information on the current status of this and other ETSI documents is available at 

http://portal.etsi.orq/tb/status/status.asp 

If you find errors in the present document, please send your comment to one of the following services: 

http://portal.etsi.orq/chaircor/ETSI support.asp 

Copyright Notification 

No part may be reproduced except as authorized by written permission. 
The copyright and the foregoing restriction extend to reproduction in all media. 

© European Telecommunications Standards Institute 2010. 
All rights reserved. 

DECT™, PLUGTESTS™, UMTS™, TIPHON™, the TIPHON logo and the ETSI logo are Trade Marks of ETSI registered 

for the benefit of its Members. 
3GPP™ is a Trade Mark of ETSI registered for the benefit of its Members and of the 3GPP Organizational Partners. 

LTE™ is a Trade Mark of ETSI currently being registered 

for the benefit of its Members and of the 3GPP Organizational Partners. 

GSM® and the GSM logo are Trade Marks registered and owned by the GSM Association. 



ETSI 



3GPP TS 29.1 98-1 4 version 9.0.0 Release 9 2 ETSI TS 1 29 1 98-1 4 V9.0.0 (201 0-01 ) 



Intellectual Property Rights 



IPRs essential or potentially essential to the present document may have been declared to ETSI. The information 
pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found 
in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in 
respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web 
server ( http://webapp.etsi.org/IPR/home.asp ). 

Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee 
can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web 
server) which are, or may be, or may become, essential to the present document. 



Foreword 

This Technical Specification (TS) has been produced by ETSI 3rd Generation Partnership Project (3GPP). 

The present document may refer to technical specifications or reports using their 3GPP identities, UMTS identities or 
GSM identities. These should be interpreted as being references to the corresponding ETSI deliverables. 

The cross reference between GSM, UMTS, 3GPP and ETSI identities can be found under 
http://webapp.etsi.org/kev/quervform.asp . 



ETSI 



3GPP TS 29.1 98-1 4 version 9.0.0 Release 9 3 ETSI TS 1 29 1 98-1 4 V9.0.0 (201 0-01 ) 



Contents 



Intellectual Property Rights 2 

Foreword 2 

Foreword 9 

Introduction 9 

1 Scope 11 

2 References 11 

3 Definitions and abbreviations 11 

3.1 Definitions 11 

3.2 Abbreviations 12 

4 Presence and Availability Management SCF 12 

4.1 Introduction 12 

4.2 Motivation 12 

4.3 Goals 12 

4.4 Concepts 13 

4.4.1 Identity 13 

4.4.2 Agent 13 

4.4.3 Presence 14 

4.4.4 Availability 14 

4.4.5 Events 15 

4.5 Scope of PAM information 16 

4.6 Security and privacy 16 

5 Sequence Diagrams 17 

5.1 Use of authentication tokens 17 

5.2 Event registration and notification 18 

6 Class Diagrams 19 

6.1 PAM Provisioning SCF Class Diagrams 19 

6.2 PAM Access SCF Class Diagrams 21 

6.3 PAM Event SCF Class Diagrams 22 

7 The Service Interface Specifications 23 

7.1 Interface Specification Format 23 

7.1.1 Interface Class 23 

7.1.2 Method descriptions 24 

7.1.3 Parameter descriptions 24 

7.1.4 State Model 24 

7.2 Base Interface 24 

7.2.1 Interface Class Iplnterface 24 

7.3 Service Interfaces 24 

7.3.1 Overview 24 

7.4 Generic Service Interface 24 

7.4.1 Interface Class IpService 24 

7.4.1.1 Method setCallbackO 25 

7.4.1.2 Method setCallbackWithSessionlDQ 25 

8 Presence and Availability Management Interface Classes 26 

8.1 PAM Provisioning SCF Interface Classes 26 

8.1.1 Interface Class IpPAMProvisioningManager 26 

8.1.1.1 Method getAuthTokenO 27 

8.1.1.2 Method obtainlnterfaceO 27 

8.1.1.3 Method getAccessControlQ 28 

8.1.1.4 Method setAccessControlQ 28 

8.1.2 Interface Class IpPAMIdentityManagement 29 



£75/ 



3GPP TS 29.1 98-1 4 version 9.0.0 Release 9 4 ETSI TS 1 29 1 98-1 4 V9.0.0 (201 0-01 ) 

8.1.2.1 Method createldentityO 30 

8.1.2.2 Method deleteldentityO 31 

8.1.2.3 Method isIdentityO 31 

8.1.2.4 Method createGroupIdentityO 32 

8.1.2.5 Method deleteGroupIdentityO 32 

8.1.2.6 Method addToGroupO 32 

8.1.2.7 Method removeFromGroupO 33 

8.1.2.8 Method listMembersQ 33 

8.1.2.9 Method isGroupIdentityO 34 

8.1.2.10 Method listGroupMembershipO 34 

8.1.2.11 Method addAliasO 35 

8.1.2.12 Method removeAHasesQ 35 

8.1.2.13 Method listAliasesO 36 

8.1.2.14 Method lookupByAliasO 36 

8.1.2.15 Method associateTypes() 36 

8.1.2.16 Method disassociateTypes() 37 

8.1.2.17 Method listTypesOfldentityO 37 

8.1.2.18 Method hasTypeO 38 

8.1.2.19 Method getldentityAttributesO 38 

8.1.2.20 Method setldentityAttributesQ 39 

8.1.3 Interface Class IpPAMAgentManagement 39 

8.1.3.1 Method createAgentO 40 

8.1.3.2 Method deleteAgentO 41 

8.1.3.3 Method isAgentO 41 

8.1.3.4 Method enableCapabilitiesQ 41 

8.1.3.5 Method disableCapabilitiesQ 42 

8.1.3.6 Method listEnabledCapabilitiesQ 42 

8.1.3.7 Method listAllCapabilitiesO 43 

8.1.3.8 Method isCapableOfO 43 

8.1.3.9 Method associateTypesQ 44 

8.1.3.10 Method disassociateTypesQ 44 

8.1.3.11 Method listTypesOfAgentO 45 

8.1.3.12 Method hasTypeO 45 

8.1.3.13 Method getAgentAttributesQ 45 

8.1.3.14 Method setAgentAttributesQ 46 

8.1.4 Interface Class IpPAMAgentAssignment 47 

8.1.4.1 Method assignAgentO 47 

8.1.4.2 Method unassignAgentQ 48 

8.1.4.3 Method listAssignedAgentsQ 48 

8.1.4.4 Method listAssociatedldentitiesOfAgentQ 49 

8.1.4.5 Method listAssignedAgentsByCapabilityO 49 

8.1.4.6 Method listCapabilitiesOfldentityO 49 

8.1.4.7 Method isIdentityCapableOfO 50 

8.1.5 Interface Class IpPAMIdentityTypeManagement 50 

8.1.5.1 Method createldentityAttributeQ 51 

8.1.5.2 Method deleteldentityAttributeO 51 

8.1.5.3 Method getldentityAttributeDefinitionO 52 

8.1.5.4 Method listAllIdentityAttributesO 52 

8.1.5.5 Method createldentityTypeQ 52 

8.1.5.6 Method deleteldentityTypeO 53 

8.1.5.7 Method listldentityTypesQ 53 

8.1.5.8 Method addldentityTypeAttributesQ 54 

8.1.5.9 Method removeldentityTypeAttributesO 54 

8.1.5.10 Method listldentityTypeAttributesO 55 

8.1.6 Interface Class IpPAMAgentTypeManagement 55 

8.1.6.1 Method createAgentAttributeQ 56 

8.1.6.2 Method deleteAgentAttributeQ 56 

8.1.6.3 Method getAgentAttributeDefinitionO 57 

8.1.6.4 Method listAllAgentAttributesQ 57 

8.1.6.5 Method createAgentTypeQ 57 

8.1.6.6 Method deleteAgentTypeO 58 

8.1.6.7 Method listAgentTypesO 58 



£75/ 



3GPP TS 29.1 98-1 4 version 9.0.0 Release 9 5 ETSI TS 1 29 1 98-1 4 V9.0.0 (201 0-01 ) 

8.1.6.8 Method addAgentTypeAttributesQ 59 

8.1.6.9 Method removeAgentTypeAttributesO 59 

8.1.6.10 Method listAgentTypeAttributesQ 60 

8.1.7 Interface Class IpPAMCapabilityManagement 60 

8.1.7.1 Method createCapabilityAttributeQ 61 

8.1.7.2 Method deleteCapabilityAttributeO 61 

8.1.7.3 Method getCapabilityAttributeDefinitionQ 62 

8.1.7.4 Method listAllCapabilityAttributesO 62 

8.1.7.5 Method createCapabilityO 63 

8.1.7.6 Method deleteCapabilityO 63 

8.1.7.7 Method listCapabilitiesQ 63 

8.1.7.8 Method addCapabilityAttributesQ 64 

8.1.7.9 Method removeCapabilityAttributesQ 64 

8.1.7.10 Method listCapabilityAttributesQ 65 

8.1.7.11 Method assignCapabilitiesToType() 65 

8.1.7.12 Method unassignCapabilitiesFromType() 66 

8.1.7.13 Method listCapabilitiesOfTypeO 66 

8.2 PAM Access SCF Interface Classes 66 

8.2.1 Interface Class IpPAMPresenceAvailabilityManager 66 

8.2.1.1 Method getAuthTokenO 67 

8.2.1.2 Method obtainlnterfaceQ 67 

8.2.1.3 Method getAccessControlQ 68 

8.2.1.4 Method setAccessControlQ 68 

8.2.1.5 Method activateServiceO 69 

8.2.1.6 Method deactivateServiceO 69 

8.2.1.7 Method isActiveldentityO 69 

8.2.2 Interface Class IpPAMIdentityPresence 70 

8.2.2.1 Method setldentityPresenceO 70 

8.2.2.2 Method setIdentityPresenceExpiration() 71 

8.2.2.3 Method getldentityPresenceO 71 

8.2.3 Interface Class IpPAMAvailability 72 

8.2.3.1 Method getAvailabilityO 73 

8.2.3.2 Method getPreferenceO 74 

8.2.3.3 Method setPreferenceQ 74 

8.2.4 Interface Class IpPAMAgentPresence 75 

8.2.4.1 Method setAgentPresenceO 75 

8.2.4.2 Method setCapabilityPresenceQ 76 

8.2.4.3 Method setAgentPresenceExpiration() 76 

8.2.4.4 Method setCapabilityPresenceExpiration() 77 

8.2.4.5 Method getAgentPresenceO 77 

8.2.4.6 Method getCapabilityPresenceO 78 

8.2.5 Interface Class IpAppPAMPreferenceCheck 78 

8.2.5.1 Method computeAvailabilityO 79 

8.3 PAM Event SCF Interface Classes 79 

8.3.1 Interface Class IpPAMEventManager 79 

8.3.1.1 Method getAuthTokenO 80 

8.3.1.2 Method obtainlnterfaceQ 80 

8.3.1.3 Method getAccessControlQ 81 

8.3.1.4 Method setAccessControlQ 81 

8.3.1.5 Method activateServiceQ 82 

8.3.1.6 Method deactivateServiceQ 82 

8.3.1.7 Method isActiveldentityQ 82 

8.3.2 Interface Class IpAppPAMEventHandler 83 

8.3.2.1 Method eventNotifyQ 83 

8.3.2.2 Method eventNotifyErrQ 83 

8.3.3 Interface Class IpPAMEventHandler 84 

8.3.3.1 Method isRegisteredQ 84 

8.3.3.2 Method registerAppInterfaceQ 85 

8.3.3.3 Method registerForEventQ 85 

8.3.3.4 Method deregisterAppInterfaceQ 86 

8.3.3.5 Method deregisterFromEventQ 86 



£75/ 



3GPP TS 29.1 98-1 4 version 9.0.0 Release 9 6 ETSI TS 1 29 1 98-1 4 V9.0.0 (201 0-01 ) 

9 State Transition Diagrams 86 

10 PAM Service Properties 87 

10.1 PAM Access Service 87 

10.2 PAM Event Service 87 

11 PAM Data Definitions 87 

11.1 Entity Address Definitions 87 

11.1.1 TpPAMFQName 87 

11.1.2 TpPAMFQNameList 88 

11.2 Attribute Data Definitions 88 

11.2.1 TpPAMAttribute 88 

11.2.2 TpPAMAttributeList 88 

11.2.3 TpPAMAttributeDef 88 

11.2.4 TpPAMAttributeDefList 88 

11.3 Presence Data Definitions 89 

11.3.1 TpPAMCapability 89 

11.3.2 TpPAMCapabilityList 89 

11.3.3 TpPAMPresenceData 89 

11.3.4 TpPAMPresenceDataList 89 

11.4 Pre-defined Presence type 89 

11.4.1 Presentity 89 

11.5 Availability Data Definitions 90 

11.5.1 TpPAMAvailabilityProfile 90 

11.5.2 TpPAMAvailabilityProfileList 90 

11.5.3 TpPAMPrivacyCode 90 

11.6 Availability Context Data Definitions 90 

11.6.1 TpPAMContext 90 

11.6.2 TpPAMContextName 9 

11.6.3 TpPAMContextData 9 

11.6.4 TpPAMCommunicationContext 9 

11.6.5 TpPAMContextList 9 

11.7 Credential data definitions 9 

11.7.1 TpPAMCredential 9 

11.8 Availability and Access Control Preference Data Definitions 9 

11.8.1 IpAppPAMPreferenceCheckRef 9 

11.8.2 TpPAMAccessControlData 92 

11.8.3 TpPAMACLDefault 92 

11.8.4 TpPAMPreferenceOp 92 

11.8.5 TpPAMPreferenceType 92 

11.8.6 TpPAMPreferenceData 92 

11.9 Time data definitions 93 

11.9.1 TpPAMTimelnterval 93 

11.10 Pre-defined Entity Types and Attributes 93 

11.11 Interface name definitions 93 

11.11.1 TpPAMProvisioninglnterfaceName 93 

11.11.2 TpPAMPresenceAvailabilitylnterfaceName 94 

11.11.3 TpPAMEventlnterfaceName 94 

11.12 Event data definitions 94 

11.12.1 IpAppPAMEventHandlerRef 94 

11.12.2 TpPAMClientlD 94 

11.12.3 TpPAMEventlD 94 

11.12.4 TpPAMEventName 95 

11.12.5 TpPAMEventNameList 95 

11.12.6 TpPAMEventlnfb 95 

11.12.7 TpPAMEventlnfoList 96 

11.12.8 TpPAMNotificationlnfo 96 

11.12.9 TpPAMNotificationlnfoList 96 

11.12.10 PAM_CE_1DENT1TY_CREATED 96 

11.12.10.1 TpPAMlCEventData 96 

11.12.10.2 TpPAMlCNotificationData 97 

11.12.11 PAM_CE_1DENT1TY_DELETED 97 



£75/ 



3GPP TS 29.1 98-1 4 version 9.0.0 Release 9 7 ETSI TS 1 29 1 98-1 4 V9.0.0 (201 0-01 ) 

11.12.11.1 TpPAMIDEventData 97 

11.12.11.2 TpPAMIDNotificationData 97 

11.12.12 PAM_CE_GROUP_MEMBERSHlP_CHANGED 97 

11.12.12.1 TpPAMGMCEventData 98 

11.12.12.2 TpPAMGMCNotificationData 98 

11.12.13 PAM_CE_AGENT_CREATED 98 

11.12.13.1 TpPAMACEventData 98 

11.12.13.2 TpPAMACNotificationData 98 

11.12.14 PAM_CE_AGENT_DELETED 98 

11.12.14.1 TpPAMADEventData 99 

11.12.14.2 TpPAMADNotificationData 99 

11.12.15 PAM_CE_AGENT_ASS1GNED 99 

11.12.15.1 TpPAMAAEventData 99 

11.12.15.2 TpPAMAANotificationData 99 

11.12.16 PAM_CE_AGENT_UNASS1GNED 100 

11.12.16.1 TpPAMAUEventData 100 

11.12.16.2 TpPAMAUNotificationData 100 

11.12.17 PAM_CE_CAPAB1LITY_CHANGED 100 

11.12.17.1 TpPAMCCEventData 100 

11.12.17.2 TpPAMCCNotificationData 101 

11.12.18 PAM_CE_AGENT_CAPAB1L1TY_PRESENCE_SET 101 

11.12.18.1 TpPAMACPSEventData 101 

11.12.18.2 TpPAMACPSNotificationData 101 

11.12.19 PAM_CE_AGENT_PRESENCE_SET 101 

11.12.19.1 TpPAMAPSEventData 102 

11.12.19.2 TpPAMAPSNotificationData 102 

11.12.20 PAM_CE_1DENT1TY_PRESENCE_SET 102 

11.12.20.1 TpPAMlPSEventData 102 

11.12.20.2 TpPAMlPSNotificationData 103 

11.12.21 PAM_CE_AVA1LAB1L1TY_CHANGED 103 

11.12.21.1 TpPAMAVCEventData 103 

11.12.21.2 TpPAMAVCNotificationData 103 

11.12.22 PAM_CE_WATCHERS_CHANGED 103 

11.12.22.1 TpPAMWCEventData 104 

11.12.22.2 TpPAMWCNotificationData 104 

11.12.22.3 TpPAMwatcherChangeType 104 

11.13 Error Types 104 

11.13.1 TpPAMErrorCause 104 

11.13.2 TpPAMErrorlnfo 105 

12 Presence and Availability Management Exception Classes 106 

Annex A (normative): OMG IDL Description of Presence and Availability Management 

SCF 107 

Annex B (informative): W3C WSDL Description of the Presence and Availability 

Management SCFs 108 

Annex C (informative): Java^^ API Description of the Presence and Availability 

Management SCFs 109 

Annex D (informative): Description of Presence and Availability Management for 3GPP2 

cdma2000 networks 110 

D.l General Exceptions 110 

D.2 Specific Exceptions 110 

D.2.1 Clause 1: Scope 110 

D.2.2 Clause 2: References 110 

D.2. 3 Clause 3: Definitions and abbreviations 110 

D.2.4 Clause 4: Presence and Availability Management SCF 110 

D.2.5 Clause 5: Sequence Diagrams 110 

D.2.6 Clause 6 Class Diagrams Ill 



£75/ 



3GPP TS 29.198-14 version 9.0.0 Release 9 8 ETSI TS 129 198-14 V9.0.0 (2010-01) 

D.2.7 Clause 7: The Service Interface Specifications 

D.2.8 Clause 8: Presence and Availability Management Interface Classes 

D.2.9 Clause 9: State Transition Diagrams 

D.2.10 Clause 10: PAM Service Properties 

D.2.11 Clause 11 : PAM Data Definitions 

D.2.12 Clause 12: Presence and Availability Management Exception Classes 

D.2.13 Annex A (normative) :OMG IDL Description of Presence and Availability Management SCF 

D.2.14 Annex C (informative): Java"^ API Description of Presence and Availability Management SCF 



Annex E (informative): Change history 112 

History 113 



£75/ 



3GPP TS 29.198-14 version 9.0.0 Release 9 



ETSI TS 129 198-14 V9.0.0 (2010-01) 



Foreword 



This Technical Specification has been produced by the 3' Generation Partnership Project (3GPP). 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 
where: 

X the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



Introduction 



The present document is part 14 of a multi-part TS covering the 3' Generation Partnership Project: Technical 
Specification Group Core Network; Open Service Access (OSA); Application Programming Interface (API), as 
identified below. The API specification (3GPP TS 29.198) is structured in the following Parts: 



Parti 
Part 2 
Part 3 
Part 4 



Parts 
Part 6 
Part? 
Parts 
Part 9 
Part 10 
Part 11 
Part 12 
Part 13 
Part 14 
Part 15: 
Part 16: 



"Overview"; 

"Common Data Definitions"; 

"Framework"; 

"Call Control"; 

Sub-part 1: "Call Control Common Definitions"; 

Sub-part 2: "Generic Call Control SCF"; 

Sub-part 3: "Multi-Party Call Control SCF"; 

Sub-part 4: "Multi-Media Call Control SCF"; 

Sub-part 5: "Conference Call Control SCF"; 

"User Interaction SCF"; 

"Mobility SCF"; 

"Terminal Capabihties SCF"; 

"Data Session Control SCF"; 

"Generic Messaging SCF"; 

"Connectivity Manager SCF"; 

"Account Management SCF"; 

"Charging SCF". 

"Policy Management SCF"; 

"Presence and Availability Management SCF"; 

"Multi Media Messaging SCF"; 

"Service Broker SCF". 



(not part of 3GPP Release 8) 
(new in Release 8) 



The Mapping specification of the OSA APIs and network protocols (3GPP TR 29.998) is also structured as above. 
A mapping to network protocols is however not applicable for all Parts, but the numbering of Parts is kept. 
Also in case a Part is not supported in a Release, the numbering of the parts is maintained. 
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OSA API specifications 29.198-family 


OSA API Mapping - 29.998-family 


29.198-01 


Overview 


29.998-01 


Overview 


29.198-02 


Common Data Definitions 


29.998-02 


Not Applicable 


29.198-03 


Framework 


29.998-03 


Not Applicable 


Call 
Control 
(CC) 
SCF 


29.198- 
04-1 

Common 
CC data 
definitions 


29.198- 
04-2 
Generic 
CCSCF 


29.198- 
04-3 
Multi- 
Party 
CCSCF 


29.198- 
04-4 
Multi- 
media 
CCSCF 


29.198- 
04-5 
Conf 
CCSCF 


29.998-04-1 


Generic Call Control - CAP mapping 


29.998-04-2 


Generic Call Control - INAP mapping 


29.998-04-3 


Generic Call Control - Megaco mapping 


29.998-04-4 


Multiparty Call Control - ISC mapping 


29.198-05 


User Interaction SCF 


29.998-05-1 


User Interaction - CAP mapping 


29.998-05-2 


User Interaction - INAP mapping 


29.998-05-3 


User Interaction - Megaco mapping 


29.998-05-4 


User Interaction - SMS mapping 


29.198-06 


Mobility SCF 


29.998-06-1 


User Status and User Location - MAP 
mapping 


29.998-06-2 


User Status and User Location - SIP mapping 


29.198-07 


Terminal Capabilities SCF 


29.998-07 


Not Applicable 


29.198-08 


Data Session Control SCF 


29.998-08 


Data Session Control - CAP mapping 


29.198-09 


Generic Messaging SCF 


29.998-09 


Not Applicable 


29.198-10 


Connectivity Manager SCF 


29.998-10 


Not Applicable 


29.198-11 


Account Management SCF 


29.998-11 


Not Applicable 


29.198-12 


Charging SCF 


29.998-12 


Not Applicable 


29.198-13 


Policy Management SCF 


29.998-13 


Not Applicable 


29.198-14 


Presence & Availability Management SCF 


29.998-14 


Not Applicable 


29.198-15 


Multi-media Messaging SCF 


29.998-15 


Not Applicable 


29.198-16 


Service Broker SCF 


29.998-16 


Not Applicable 
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Scope 



The present document is part 14 of the Stage 3 specification for an Apphcation Programming Interface (API) for Open 
Service Access (OS A). 

The OS A specifications define an architecture that enables application developers to make use of network functionality 
through an open standardised interface, i.e. the OSA APIs. The concepts and the functional architecture for the OSA 
are contained in 3GPP TS 23.198 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The present document specifies the Presence and Availability Management Service Capability Feature (SCF) aspects of 
the interface. All aspects of the Presence and Availability Management SCF are defined here, these being: 

• Sequence Diagrams 

• Class Diagrams 

• Interface specification plus detailed method descriptions 

• State Transition diagrams 

• Data Definitions 

• IDL Description of the interfaces 

The process by which this task is accomplished is through the use of object modelling techniques described by the 
Unified Modelhng Language (UML). 

This specification has been defined jointly between 3GPP TSG CT WG5, ETSI TISPAN and the Parlay Group, in co- 
operation with a number of JAIN^"^ Community member companies. 



References 



The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 

• References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

• For a specific reference, subsequent revisions do not apply. 

• For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TS 29.198-1: "Open Service Access; Application Programming Interface; Part 1: 

Overview" . 

[2] 3GPP TS 22. 127: "Service Requirement for the Open Service Access (OSA); Stage 1 ". 

[3] 3GPP TS 23.198: "Open Service Access (OSA); Stage 2". 



3 Definitions and abbreviations 

3.1 Definitions 

For the purposes of the present document, the terms and definitions given in TS 29.198-1 [1] apply. 
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3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in TS 29.198-1 [1] apply. 

4 Presence and Availability Management SCF 

4.1 Introduction 

The goal of these interfaces is to establish a standard for maintaining, retrieving and publishing information about 

• Presence and Availability of entities for various forms of communication and the contexts in which they are 
available; 

• Characteristics and presence status of agents (representing capabilities for communication, content 
delivery, etc.). 

4.2 Motivation 

Consider the following simple but desirable scenario for a communication service: An end-user wishes to receive 
instant messages from her management at any time on her mobile phone, from co-workers only on her desktop 
computer, and in certain cases for the messages to be forwarded to e-mail or even a fax machine/printer. The senders 
may know her availability for various forms of communication in the way she chooses to reveal it or alternatively the 
senders may never know how she will be receiving their messages. This scenario spans over multiple services and 
protocols and can only be solved currently by a proprietary solution that maintains the required information in an ad- 
hoc fashion within the application. 

PAM is not a replacement for the protocols being standardized for various communication and network services. PAM 
attempts to standardize the management and sharing of presence and availability information across multiple services 
and networks. 

The PAM specification is motivated by the observations that 

• The notions of Identity, Presence and Availability are common to but independent of the various communication 
technologies, protocols and applications that provide services using these technologies. 

• Presence does not necessarily imply availability. End-users or organizations require greater control over making 
themselves available through various communication devices. 

• Presence based services need to address privacy concerns on who can access presence information and under 
what conditions. 

Management of availability will span over multiple communication services and service providers. 

4.3 Goals 

The purpose of this document is to adopt the first release of a Presence and Availability Management interface 
specification created by an industry consortium, PAM forum, established for this purpose harmonized with the IETF 
model for presence (RFC 2778). This specification is also consistent with the ongoing work in 3GPP for defining the 
requirements and architecture for a standard presence service in the network. 

With a desired goal of rapid acceptance and usage, the specification has been deliberately designed to be as simple as 
possible with an attempt to include a minimal set of functionality that is sufficient for use in non-trivial applications. 
Often, this has been at the cost of some useful features, which would have made the specification baroque and 
cumbersome if not controversial. 
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4.4 Concepts 



This chapter briefly describes the various concepts involved in this specification to serve as the context for the rest of 
the document. 

4.4.1 Identity 

Identity, for purposes of the PAM specification, is a limited electronic representation of an entity (i.e., an individual or 
an organization) that participates in PAM-enabled applications and services. This concept corresponds to the concept of 
Presentity as described in the IETF Common Presence and Instant Messaging Model (RFC 2778). 

The main characteristic of an entity that is central to PAM specifications is the name (or handle) by which entities are 
identified by applications and services. Entities may have multiple names, login ids, account names, etc., by which they 
are identified. As PAM attempts to abstract over multiple networks and services, it does not assume that a single name 
will necessarily identify entities across all application domains. 

The generalized structure available in 3GPP for user names that may contain various formats for addressing has been 
adopted for these specifications. 

To enable entities to be identified by any of the names associated with them, PAM identities can be assigned aliases. A 
name and a namespace pair can be defined as an alias of another name and namespace pair. It is important to note that 
aliases are just synonyms and hence have limited semantics. In particular, they are not powerful enough to model 
personas each with their own capabilities and privacy requirements. 

An identity can represent a single entity or a group of identities. Group identities have similar semantics to non-group 
identities but, in addition, maintain a list of identities that constitute the group. As an example, a sales department may 
be modelled as a group identity with the identities of the members of the department being member identities of the 
group. Group identities and their member identities do not inherit anything from each other. 

No other relationships between identities are within the scope of the PAM specifications. 

For flexibility and extensibility, attribute lists are used to associate additional data with identities. Identities are typed to 
provide a way to manage such attribute lists. An identity type may be associated with a specific set of attributes and all 
identities of that type inherit instances of such attributes. 

For consistency with IETF (RFC 2778) defined presence data models, PAM pre-defines an identity type Presentity with 
a list of presence attributes as defined in TS 22.141 based on the definitions in RFC 2778. 

PAM implementations may map certain existing directory and database data to one or more types to allow access via 
PAM interfaces. PAM specifications do not specify how the data within the profiles are to be stored. They may be 
stored within the PAM implementation or mapped to data stored on external directories and databases. 

4.4.2 Agent 

An agent, for PAM purposes, is a limited electronic representation of a software or hardware device through which 
identities manifest themselves or make themselves available to applications and services. 

An important characteristic of an agent is a list of one or more capabilities associated with it. A capability is what 
makes an agent useful. A capability either represents the ability of an agent to participate in communications and 
content delivery (e.g.: instant messaging, SMS, WAP, voice) or it represents the ability of an agent to report useful 
information (e.g. location, velocity, temperature, mood) of the environment around it. 

PAM does not specify any pre-defined capabilities. Applications may define and use their own capabilities. 

Agent instances are identified by names (or handles). As for identities, names exist in the context of a namespace. 
Within a namespace, a name is assumed to be unique. Two agent instances can have the same name as long as they are 
in different namespaces. For example, a mobile phone and a PDA manufactured by two different manufacturers may 
coincidentally have the same serial number by which they are identified. As PAM attempts to unify services over 
multiple technologies, it does not assume that a name uniquely identifies agent instances across all technologies or 
across all manufacturers. They can be disambiguated through the use of namespaces. 

No relationships between agents are within the scope of the PAM specifications. 
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For flexibility and extensibility, attribute lists are used to associate additional data with agents. Agents are typed to 
provide a way to manage such attribute lists. An agent type may be associated with a specific set of attributes and all 
agents of that type inherit instances of such attributes. 

PAM does not specify any pre-defined attributes or types. Applications may define and use their own agent types. 

PAM implementations may map certain existing directory and database data to one or more types to allow access via 
PAM interfaces. PAM specifications do not specify how the data within the profiles are to be stored. They may be 
stored within the PAM implementation or mapped to data stored on external directories and databases. 

Agent instances are associated with one or more identities. This association results in the inheritance of associated 
agents' capabilities by the identities. 

4.4.3 Presence 

The concept of presence has been used in several application areas, being most explicit in Instant Messaging. Starting 
from a simple notion of online/offline status, it has expanded to include other context information around the status such 
as disposition (out to lunch, away from the computer, etc.) and activity status (on the phone, idle, etc.). Location 
information, on the other hand, has largely been kept separate from what has been traditionally considered presence 
information. PAM specifications broaden the concepts of presence recognizing that all such information, including 
location, describes different contexts of an entity's existence. The unifying property is that the presence information is 
continually changing and that there is value in knowing the current information at different points in time for services 
and applications. 

For the purposes of PAM specifications, presence is an extensible set of characteristics that captures the dynamic 
context in which an identity or an agent exists at any point in time. In contrast to the relatively static information about 
identities or agents (e.g., names, addresses, capabilities), presence refers to dynamic information such as location, 
status, disposition, etc. Registrations of presence and location information in existing applications are covered by this 
definition. 

Presence information is differentiated from the more static information associated with identities and agents that are 
stored in attributes. The rationalization for this design is that the presence information is dynamic and has implications 
on the implementation. Some of the presence information is too dynamic to be maintained in static data stores such as 
directories and without this hint about the data characteristics, PAM implementers may make sub-optimal decisions on 
the way the data is stored. Second, presence information typically has expiration data that needs to be understood by the 
implementation. 

The PAM specification recognizes that devices that provide presence information are not necessarily devices that 
communicate. 

The PAM specification does not specify the methods by which the presence information is derived. For example, an 
instant messaging client on a desktop computer can register its status based on when a user is logged in. A mobile 
phone may do an explicit registration on a WAP server for instant messaging. The phone's presence for voice calls, on 
the other hand, may be inferred implicitly by querying the cellular network for the device being on when requested. The 
presence of an identity, on the other hand, may be computed using presence information from one or more devices 
owned by the identity. 

Finally, the PAM specification does not require that the presence information be stored explicitly (i.e., in a materialized 
fashion) in a PAM implementation. An implementation may infer the presence information on demand from the 
underlying services or networks. 

For compatibility with the presence model from IETF (RFC 2778), a type called Presentity is pre-defined with the 
attributes consistent with the IETF Presence model. 



4.4.4 Availability 



Availability is a property of an identity denoting its ability and willingness to share information about itself or to 
communicate with another identity based on factors such as the type of communication requested, the identity of the 
calling entity and the preferences and policies that are associated with the recipient. This is the primary means by which 
the current PAM specification enables controls for privacy. While presence is, in most applications, a necessity for 
availability, presence does not necessarily imply availability to all. 
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Availability is always with respect to a context. A context in PAM specifications is a set of attributes defining the state 
in which the availability is requested. For example, the query "Is Jane available for IM for Rob?" identifies the type of 
communication and the identity of the asker as the context. PAM allows for availability to be differentiated based on 
any attribute of a context. A context, "Communication" is pre-defined in PAM. 

Most queries for presence in existing applications can be mapped into PAM availability queries to control the 
information being given out. Alternatively, queries can be mapped directly into PAM presence queries in situations 
where privacy controls and policies are not required or all presence data is open to the entity querying. This allows 
PAM specifications to be consistent with existing presence servers and to serve as the basis for presence services across 
multiple protocols while providing uniform and flexible privacy controls. 

PAM specification does not specify whether the availability is computed on demand or stored explicitly. In some 
applications, the availability may be pre-computed and stored explicitly while in some, it may be computed at each 
request for availability. 

While the PAM specification provides a mechanism to associate preferences with an Identity to control availability, it 
neither specifies the syntax and semantics of the preferences nor the process by which the availability is computed. 
These aspects are left to the implementation. 

For example, a particular implementation may provide the facility to store preferences as rules such as "I prefer to 
receive my instant messages on my computer rather than my cell phone unless the message is from my boss or the 
computer is off, etc.". 

As an example, a computation of availability for communication may consist of the following algorithm: 

1) Find all devices of the identity being called that are capable of the specified form of communication AND have 
registered their presence status as available. 

2) Evaluate the rules associated with the identity being called to select the preferred device(s) from the set of 
present devices determined in Step 1 . 

3) If there are any devices available satisfying Step 2, indicate the availability of the identity being called via the 
available devices. 

An implementation can chose to provide one or more means to specify preferences. It is expected that if there is 
industry standardization on the specification of preferences, the implementations will support such a standard. This is 
currently outside the scope of PAM. 

4.4.5 Events 

Events are representations of certain identified occurrences related to the concepts described above. The PAM 
specification provides for registering interest (i.e., callbacks) in being notified of such occurrences. Any entity that 
subscribes to the Event is a "watcher" in the IETF terminology (RFC 2778). An implementation is expected to provide 
such notifications. 

Examples of events include, 

• Creation/deletion of an identity. 

• Association of an agent instance with an identity. 

• Change in presence status or location of an agent instance. 

• Change in the presence information of an identity 

• Change in availability of an identity for a particular form of communication 

PAM specifications contain a set of pre-defined events. Each event is defined by a name of the event, a set of input 
attribute value pairs that must be provided when an event is registered for and a set of attribute value pairs that are 
included in the notifications sent out when the event of interest occurs. 
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4.5 Scope of PAM information 

Presence and Availability Management has the following types of information in its scope: 

• Identities, which consist of names and aliases of entities participating in communications. 

• Agent information, which consists of names and communication capabilities of software and/or hardware 
devices. 

• Agent provisioning, which consists of associations between instances of agents and identities. 

• Presence information, which consists of an identity's dynamic characteristics such as status and geographical 
location. 

• Availability information, which consists of preferences associated with identities and computation of 
availability, based on the devices present and the current preferences. 

• Notification of changes to the above pieces of information. 

• Security issues for access to this information. 

The PAM specification consists of interfaces to manage or access the above information. 
The specification purposefully does not include 

• Storage design or storage requirements for any of the presence and availability information. 
These are to be decided by specific implementations of the PAM specification. 



4.6 Security and privacy 



As the Presence and Availability Management interface is designed to share information across administrative domains 
and to facilitate availability computation based on the identity of the entity desiring communication, security and 
privacy issues are addressed in the design. Two of the issues considered to be within the scope of PAM are: 

• Access control to an implementation of the PAM specification. 

• Use of an authenticated entity' s credentials by methods in the specification. 

To understand the distinction between the first two issues, consider, for example, an end-user that logs on to an Instant 
Messaging client and wishes to send a message. The client (or a gateway to which the client talks to) may access a PAM 
implementation to determine the availability of the destination for the message. The client (or the gateway) will need to 
be authorized for access to the PAM implementation independent of the user that logs in. A gateway may, in fact, do 
this access on behalf of a number of clients and, for performance reasons, wish to authenticate itself just once on start 
up rather than at each invocation. This authentication is handled by the authentication mechanisms in the OSA 
Framework common to all services within OSA. 

Second, each invocation of a particular method will need to contain the credentials of the end-user that logged into the 
client so that the computation of the availability can take that into account when necessary for privacy issues. 

It should be noted that the PAM specification allows for the possibility that the authentication of the end-users is not 
necessarily done within the PAM implementation itself. As long as the authenticated credentials supplied by the client 
(or gateway) are acceptable for validation and the client (or the gateway) itself is authenticated by the implementation, 
the authentication of end-users can occur anywhere outside the PAM implementation. A deployment scenario for a 
particular application is that one or more authentication services are provided as external services over PAM 
implementations. 

This design does not preclude the possibility that the client (or the gateway) cannot be authenticated. Therefore, the 
credentials supplied by the client (or the gateway) may be held to stronger authentication criterion than credentials 
supplied by a trusted client (or gateway). 

Finally, the PAM specification does not mandate the use of authentication within an implementation if the environment 
in which it is used does not require it. 
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Clause 5.1 explains the mechanism for providing data about the asker to each of the methods with a sequence diagram. 

Privacy issues are addressed primarily by providing a mechanism to control the information flowing out of a PAM 
implementation based on whatever criterion the end user may choose to specify in the availability preferences and 
independent of any particular application. 

The following security issues were considered to be outside the scope of PAM: 

• Authentication of the identity of the end-users or entities. As explained above, this authentication may be 
provided by a third-party authentication service or it may occur through an authentication service written over 
the PAM platform. The only requirement is that the type of credentials supplied by the authentication service be 
acceptable to the PAM platform implementation being accessed. 

• Encryption of the flow of information between a PAM platform implementation and clients of this 
implementation. This is dependent on the method of access to the interface which is outside the scope of the 
PAM specification and hence to be determined by the implementation. 



Sequence Diagrams 



Most of the methods in the PAM interfaces are independently used to query or update presence and availability related 
information with no transactions or state transitions involved. There are two use cases for which sequence diagrams are 
useful 

• Acquiring and using authentication tokens 

• Registering for PAM events and getting notifications on the occurrence of the event. 

The sequence diagrams for these two cases are provided below. It is assumed that the authentication with the OSA 
framework has already occurred and the application has access to the PAM interfaces. 

5.1 Use of authentication tokens 

As an OSA Service, PAM uses the authentication features of the OSA Framework to provide access control to the PAM 
interfaces. In addition, PAM provides an optional mechanism for service/application level identification and 
authentication of the entity requesting the operation or alternatively on whose behalf the operation is being requested. 
To handle privacy requirements, the results of presence and availability data updates or queries are dependent on the 
entity requesting the operations. 

In the simplest case, the entity authenticating to the OSA Framework to get access to the service interface is the entity 
requesting the operation. In general, however, a proxy or an application (such as a messaging server or a conferencing 
server) may authenticate with the OSA Framework once and then check for presence and availability on behalf of 
multiple client applications (such as instant messaging clients). The credential of these client applications if and when 
needed by the PAM service can then be provided via the credential parameter in each of the interface methods. 

The mechanism to provide the asker data is via the optional parameter of type TpPAMCredential in each of the 
methods. Supplying the entire asker data in each of the methods is expensive for an implementation since it will need to 
parse and validate the data supplied in the asker data structure each time. An application may be accessing multiple 
methods for itself or for the benefit of end user(s) and will need to supply the relevant asker data in each case. To make 
the consideration of asker data more efficient, the application uses the getAuthToken() method in each of the managers 
in the SCFs once for each session per asker and gets a credential that can be reused as many times as necessary in the 
same session to represent the same asker. 

The sequence diagram for an example usage is given below. 
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gient 



IpPAMPresenceAvailabilitvManaqer IpPAMIdentityPresence 



1 : getAuthToken( 



^ 



2: getldentityPresence( ) 



IpPAMAvailabilitv 



->^ 



3: getAvailability( 



1: For any unique entity requesting the operation, the authenticated client of the OS A PAM service, requests for an 
authentication token using the getAuthToken() method in the PresenceAvailabiUty Manager interface. 

2: The token returned by the getAuthToken() method is used as the credential parameter of the getIdentityPresence() 
request. 

3; The same token is used as the credential parameter of the getAvailabilityO request(). An authorization token can be 
used multiple times within the same session established with OSA framework. 



5.2 Event registration and notification 

An OSA client can register for certain events in the PAM service either for itself or on behalf of its own clients. The 
client will register one or more application interfaces with the event management service and then activate one or more 
events for each such registered interface. 

The sequence diagram for an example is given below. 
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: IpAppPAMEventHandler 



: IpPAMEventHandler 



1 : regis terApplnterface( 



2: getAuthfoken( ) 



3: registerForE\ent( 



-^ 



5: e«AtNotify( ) 



Client 2 



IpPAMEventManaqer bPAMIdentitvPresence 



-^ 



4: setldentityPresence( 



1: The client uses the registerAppInterface() method to register its notification interface. The getAuthToken() can be 
null since the client is doing this registration on its own behalf. The client gets a unique client ID back. 

2: The client uses the getAuthToken() to get authentication credentials for its own apphcation chent on behalf of whom 
an event registration is required. 

3: The client uses the registerForEvent() method to register for a change in availability event on behalf of its own 
client. The client gets a unique event ID back. 

4: The presence information for an identity of interest in 3 above is changed by another client application acting on its 
behalf using the setIdentityPresence() method. 

5: When the change in presence results in a change in the availability of the identity for the client that has registered 
for the availability change, a notification is sent out using the previously registered application interface. 



Class Diagrams 



PAM consists of the following SCFs: 

• PAM Provisioning Service consisting of Interfaces to provision identities, agents and relationships between them 

• PAM Access Service consisting of interfaces to view and update presence and availability information and 

• PAM EventManagement Service consisting of interfaces to subscribe to events in PAM and be notified of such 
events. 

6.1 PAM Provisioning SCF Class Diagrams 

PAM Provisioning Service contains the following service interfaces. It contains no application interfaces. 

IpPAMIdentityManagement 

- The purpose of this interface is to manage subscriber names, aliases, groups and sets of attributes called Profiles 
associated with subscribers. 

IpPAMAgentManagement 
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- The purpose of this interface is to manage agent (that models a hardware or software device) names, communication 
capabilities and sets of attributes called Profiles associated with agents. 

IpPAMAgentAssignment 

- The purpose of this interface is to manage the relationship between identities and the agents assigned to them. 
IpPAMIdentityTypeManagement 

IpPAMAgentTypeManagement 
IpPAMCapabilityManagement 

- These three interfaces allow for definitions of identity types, agent types and agent capabilities used for presence and 
availability management. 

The interfaces and the relationships between them are shown in the figure below. 
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«lnterface» 
IpPAM Provisioning Manager 
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Figure: PAM Provisioning Service 



6.2 PAM Access SCF Class Diagrams 

The PAM Access service consists of two packages, one for the appHcation interfaces and one for the service interfaces. 
The appHcation PAM Access package consists of or more instances of the IpAppPAMPreferenceCheck interface and 
the PAM event management service package consists of a single instance of the following interfaces obtainable by 
applications using the service interface IpPAMPresenceAvailabilityManager. 

IpPAMAgentPresence 

- The purpose of this interface is to maintain the dynamic presence information of agents. 
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IpPAMIdentityPresence 

- The purpose of this interface is to maintain the dynamic presence information of identities. 
IpPAMAvailabilityManagement 

- The purpose of this interface is to (i) Manage the preferences specified for the availabihty of an identity (ii) Query for 
the availability of identities for specific capabilities. 

The interfaces and the relationships between them are shown in the figure below. 
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Figure: PAM Access Service 



6.3 PAM Event SCF Class Diagrams 

The PAM Event Management service consists of two packages, one for the application interfaces and one for the 
service interfaces. The application PAM event management package consists of or more instances of the 
IpAppPAMEventHandler interface and the PAM event management service package consists of a single instance of the 
IpPAMEventHandler interface. This interface can be obtained by application using the service interface 
IpPAMEventManager. 

The figure below shows the interfaces of PAM Event Management and the relationships between them. 
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«lnterfac... 
Iplnterface 

(from csapi) 



«lnterface» 
IpAppPAMEventHandler 

(from event) 



♦eventNotifyO 
♦eventNotifyErrO 



«lnterface» 
IpService 

(from csapi) 



«uses» 



«lnterface» 
IpPAMEventHandler 

(from event) 



♦isRegisteredO 
%egisterApplnterface() 
%egisterForEvent() 
_^deregisterApplnterface() 
HderegisterFrom EventO 



<- 



PsetCallbackO 
^setCallbackWithSessionlDO 



«lnterface» 
IpPAMEventManager 

(from event) 



^getAjthTokenO 
^obtain InterfaceO 

3etA;cessControl() 
|setA;cessControl() 
|acti\ateService() 

JeactivateServiceO 
|isActiveldentity() 



«uses» 



Figure: PAM Event Management Service 



7 The Service Interface Specifications 

7.1 Interface Specification Format 

This clause defines the interfaces, methods and parameters that form a part of the API specification. The Unified 
Modelling Language (UML) is used to specify the interface classes. The general format of an interface specification is 
described below. 



7.1.1 



Interface Class 



This shows a UML interface class description of the methods supported by that interface, and the relevant parameters 
and types. The Service and Framework interfaces for enterprise-based client applications are denoted by classes with 
name Ip<name>. The callback interfaces to the applications are denoted by classes with name IpApp<name>. For 
the interfaces between a Service and the Framework, the Service interfaces are typically denoted by classes with name 
IpSvc<name>, while the Framework interfaces are denoted by classes with name IpFw<name>. 
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7.1.2 Method descriptions 



Each method (API method "call") is described. Both synchronous and asynchronous methods are used in the API. 
Asynchronous methods are identified by a 'Req' suffix for a method request, and, if applicable, are served by 
asynchronous methods identified by either a 'Res' or 'Err' suffix for method results and errors, respectively. To handle 
responses and reports, the application or service developer must implement the relevant IpApp<name> or 
IpSvc<name> interfaces to provide the callback mechanism. 



7.1.3 Parameter descriptions 

Each method parameter and its possible values are described. Parameters described as 'in' represent those that must have 
a value when the method is called. Those described as 'out' are those that contain the return result of the method when 
the method returns. 

7.1.4 State Model 

If relevant, a state model is shown to illustrate the states of the objects that implement the described interface. 

7.2 Base Interface 

7.2.1 Interface Class Iplnterface 

All application, framework and service interfaces inherit from the following interface. This API Base Interface does not 
provide any additional methods. 



«lnterface» 
Iplnterface 



7.3 Service Interfaces 
7.3.1 Overview 

The Service Interfaces provide the interfaces into the capabilities of the underlying network - such as call control, user 
interaction, messaging, mobility and connectivity management. 

The interfaces that are implemented by the services are denoted as 'Service Interface'. The corresponding interfaces that 
must be implemented by the application (e.g. for API callbacks) are denoted as 'Application Interface'. 

7.4 Generic Service Interface 
7.4.1 Interface Class IpService 

Inherits from: Iplnterface 

All service interfaces inherit from the following interface. 
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«lnterface» 
IpService 



setCallback (applnterface : in IplnterfaceRef) : void 

setCallbackWitinSessionlD (applnterface : in IplnterfaceRef, sessionID : in TpSessionID) : void 



7.4.1.1 Method setCallback() 

This method specifies the reference address of the callback interface that a service uses to invoke methods on the 
application. It is not allowed to invoke this method on an interface that uses SessionlDs. Multiple invocations of this 
method on an interface shall result in multiple callback references being specified. The SCS shall use the most recent 
callback interface provided by the application using this method. In the event that a callback reference fails or is no 
longer available, the next most recent callback reference available shall be used. 

Parameters 

applnterface : in IplnterfaceRef 

Specifies a reference to the application interface, which is used for callbacks. 

Raises 

TpCoirmonExceptions , P_INVALID_INTERFACE_TYPE 



7.4.1.2 Method setCallbackWithSessionlD() 

This method specifies the reference address of the application's callback interface that a service uses for interactions 
associated with a specific session ID: e.g. a specific call, or call leg. It is not allowed to invoke this method on an 
interface that does not use SessionlDs. Multiple invocations of this method on an interface shall result in multiple 
callback references being specified. The SCS shall use the most recent callback interface provided by the application 
using this method. In the event that a callback reference fails or is no longer available, the next most recent callback 
reference available shall be used. 

Parameters 

applnterface : in IplnterfaceRef 

Specifies a reference to the application interface, which is used for callbacks. 

sessionID : in TpSessionID 

Specifies the session for which the service can invoke the application's callback interface. 
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Raises 

TpCoirmonExceptions, PINVALIDSESSIONID, PINVALIDINTERFACETYPE 



8 Presence and Availability Management Interface 

Classes 

PAM consists of the following SCFs 

• PAM Provisioning Service 

• PAM Access Service 

• PAM Event Service 

The PAM Provisioning service consists of the Identity Management, Agent Management, Agent Assignment, Agent 
Type Management, Identity Type Management and Capability Management interfaces. 

The PAM Access service consists of the identity presence and availability interfaces. 

The Event service consists of the Event Management interfaces. 

An implementation of this API which supports or implements a method described in the present document, shall 
support or implement the functionality described for that method, for at least one valid set of values for the parameters 
of that method. Where a method is not supported by an implementation of a Service interface, the exception 
P_METHOD_NOT_SUPPORTED shall be returned to any call of that method. 

8.1 PAM Provisioning SCF Interface Classes 

This service consists of interfaces to provision identities, agents and the relationships between them. 

8.1 .1 Interface Class IpPAMProvisioningManager 

Inherits from: IpService. 

The purpose of this interface is to supply the various interfaces available in this service to the application and to provide 
the authentication credentials. This interface is the only discoverable interface from the framework. 

All PAM methods use an authentication token as a parameter since the outcome of the operations may depend on 
the entity requesting the operation. To enable this, the getAuthToken() method is used to obtain an implementation 
dependent token. An application that has authenticated itself with the OSA framework, can get an authentication token 
for itself. Alternatively, if the application is requesting PAM operations on behalf of multiple entities, authentication 
tokens may be requested for each such entity after providing any available data about the asker. These tokens can then 
be used repeatedly for operations within a session without further need to identify the asker. 
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«lnterface» 
IpPAMProvisioningManager 



getAuthToken (askerData : in TpAttributeList) : TpPAMCredential 

obtainlnterface (interfaceName : in TpPAMProvisioninglnterfaceName) : IplnterfaceRef 

getAccessControl (identity : in TpPAMFQName, autin Token : in TpPAMCredential) : 
TpPAMAccessControlData 

setAccessControl (identity : in TpPAMFQName, operation : in TpPAMPreferenceOp, newAccessControl : in 
TpPAMAccessControlData, authToken : in TpPAMCredential) : void 



8.1 .1 .1 Method getAuthToken () 

Get an authentication token for access to the interface methods. 

Returns an implementation-dependent authentication credential that can be verified. 

Parameters 

askerData : in TpAttributeList 

Specifies information about the asker. Can be an empty array. The exact attributes in this list are dependent on the 
application. PAM reserves the attribute "name" with type TpPAMFQName to contain the identity of the asker if known. 

Returns 
TpPAMCredential 

Raises 

TpCoimnonExceptions, P PAMINVALIDCREDENTIAL 



8.1 .1 .2 Method obtain InterfaceQ 

Obtain available interfaces from the service. The valid parameters for this method can be obtained from the service 
property P_OBTAINABLE_INTERFACES. 

Returns the requested interface. 

Parameters 

interfaceName : in TpPAMProvisioninglnterfaceName 
Specifies the name of the required interface. 
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Returns 
IpInterfaceRef 

Raises 

TpCommonExceptions , P_PAM_UNAVAILABLE_INTERFACE 



8.1 .1 .3 Method getAccessControl() 

Get the access control associated with the data belonging to an identity. The data associated with an identity includes 
the static and dynamic attributes of an identity as well as data about agents associated with an identity. 

This method should be used in conjunction with the setAccessControl method. 

Returns the access control if previously specified for the identity. Is null if there is no access control associated. 

Parameters 

identity : in TpPAMFQName 
Specifies the identity of interest. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMAccessControlData 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 



8.1 .1 .4 Method setAccessControl() 

Set the access controls for the data associated with the specified identity. If the identity is Null, the access control is set 
for all identities (if authorized to do so). The data associated with an identity includes the static and dynamic attributes 
of an identity as well as data about agents associated with an identity. 

Any existing access control will be modified based on the operation. 

If the new access control is specified as Null for replace operation , an existing access control will be removed. 

Parameters 

identity : in TpPAMFQName 
Specifies the identity of interest. 

operation : in TpPAMPreferenceOp 

Specifies the operation to be performed with the specified preference. 

newAccessControl : in TpPAMAccessControlData 

Specifies the access controls to add. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Raises 

TpCoirmonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 



8.1 .2 Interface Class IpPAMIdentityManagement 

Inherits from: Iplnterface. 

The purpose of this interface is to manage end-user or entity names, aliases, groups and sets of attributes associated with 
identities. An implementation may map these methods to operations on existing directories or databases. Some 
implementations may choose to provide a read-only access to the identity information. 

The names of identities within a namespace must be unique. Each implementation exports an identifier as the default 
namespace that it serves. The identity name and the namespace may be used as an alias to another identity in a different 
namespace. 

Aliases are associated with a given identity or group identity. Aliases must be uniquely assigned. In other words, 
two identities may not share the same alias. 

This interface is meant for use by provisioning applications that establish and maintain identity names. 
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«lnterface» 
IpPAMIdentityManagement 



createldentity (identity : in TpPAMFQName, identityTypes : in TpStringList, autiiToken : in 
TpPAMCredential) : void 

deleteldentity (identity : in TpPAMFQName, authToken : in TpPAMCredential) : void 

isldentity (identity : in TpPAMFQName, autliToken : in TpPAMCredential) : TpBoolean 

createGroupldentity (identity : in TpPAMFQName, identityTypes : in TpStringList, authToken : in 
TpPAMCredential) : void 

deleteGroupldentity (identity : in TpPAMFQName, authToken : in TpPAMCredential) : void 

addToGroup (group : in TpPAMFQName, member : in TpPAMFQName, authToken : in TpPAMCredential) : 
void 

removeFromGroup (group : in TpPAMFQName, identity : in TpPAMFQName, authToken : in 
TpPAMCredential) : void 

listMembers (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpPAMFQNameList 

isGroupldentity (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpBoolean 

listGroupMembership (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpPAMFQNameList 

addAlias (identity : in TpPAMFQName, alias : in TpPAMFQName, authToken : in TpPAMCredential) : void 

removeAliases (identity : in TpPAMFQName, alias : in TpPAMFQName, authToken : in TpPAMCredential) : 
void 

listAliases (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpPAMFQNameList 

lookupByAlias (alias : in TpPAMFQName, authToken : in TpPAMCredential) : TpPAMFQName 

associateTypes (identity : in TpPAMFQName, identityTypes : in TpStringList, authToken : in 
TpPAMCredential) : void 

disassociateTypes (identity : in TpPAMFQName, identityTypes : in TpStringList, authToken : in 
TpPAMCredential) : void 

listTypesQfldentity (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpPAMFQNameList 

hasType (identity : in TpPAMFQName, typeName : in TpString, authToken : in TpPAMCredential) : 
TpBoolean 

getldentityAttributes (identity : in TpPAMFQName, IdentityType : in TpString, attributeNames : in 
TpStringList, authToken : in TpPAMCredential) : TpPAMAttributeList 

setldentityAttributes (identity : in TpPAMFQName, IdentityType : in TpString, attributes : in 
TpPAMAttributeList, authToken : in TpPAMCredential) : void 



8.1.2.1 Method createldentityO 

Create a new non-Group Identity with the specified name. Names must be unique across both group identities and non- 
group identities. Names must be unique across types within a namespace. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be created. 
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identity-Types : in TpStringList 

Specifies the identity's associated types. Can be an empty array. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCoirmonExceptions, PPAMIDENTITYEXISTS, PPAMUNKNOWNTYPE , 
P PAM INVALID CREDENTIAL 



8.1 .2.2 Method deleteldentity() 

Delete the specified identity and all its related data. Upon successful completion, associated aliases and attribute 
instances are deleted from the system. The identity is also removed from all groups of which the identity is a member. 

Parameters 

identity : in TpPAMFQName 
Specifies the Identity to be deleted. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCoirmonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1.2.3 Method isldentityO 

Check if the specified non-group Identity exists. The method returns false for group identities. 
Returns true if an identity with the specified name exists and false otherwise. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be checked. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCoirmonExceptions , PPAMINVALIDCREDENTIAL 
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8.1.2.4 Method createGroupldentity() 

Create a new Group Identity with the specified name. Name must be unique across both group identities and non-group 
identities. Names must be unique across the same types. 

Parameters 

identity : in TpPAMFQName 

Specifies the group Identity to be created. 

identity-Types : in TpStringList 

Specifies the group's associated types. Can be an empty array. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCoirmonExceptions, P_PAM_IDENTITY_EXISTS, P_PAM_UNKNOWN_TYPE , 
P PAM INVALID CREDENTIAL 



8.1 .2.5 Method deleteGroupldentity() 

Delete the specified group identity and all its related data. Upon successful completion, associated aliases and attribute 
instances are deleted from the system. The identity is also removed from all groups of which the identity is a member. 
The member identities of the group are not deleted. 

Parameters 

identity : in TpPAMFQName 

Specifies the group Identity to be deleted. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 



8.1 .2.6 Method addToGroupQ 

Add an existing identity to a group identity. Both the group identity and the member identity to be added must have 
been created before this operation can be invoked. A member identity can be a group identity. Implementation must not 
allow cycles in memberships. 

Parameters 

group : in TpPAMFQName 

Specifies the group Identity to which the member will be added. 
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member : in TpPAMFQName 

Specifies the identity to be added as a member of the group. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMMEMBEREXISTS, PPAMUNKNOWNGROUP , 
P PAM UNKNOWN MEMBER, P PAM IS CYCLIC, P PAM INVALID CREDENTIAL 



8.1.2.7 Method removeFromGroupO 

Remove an existing identity from the membership of a group identity. 

Parameters 

group : in TpPAMFQName 

Specifies the Group Identity from which the member will be removed. 

identity : in TpPAMFQName 

Specifies the Identity to be removed as a member of the group. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMNOTMEMBER, PPAMUNKNOWNGROUP , 
P PAM UNKNOWN MEMBER, P PAM INVALID CREDENTIAL 



8.1.2.8 Method listMembersO 

List the members of the specified group Identity. 

Returns a list of members of the specified group Identity. An empty list is returned if the identity has no members. 

Parameters 

identity : in TpPAMFQName 

Specifies the group Identity whose members are required. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Returns 
TpPAMFQNameList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_GROUP , P_PAM_INVALID_CREDENTIAL 



8.1.2.9 Method isGroupldentityO 

Check if the specified group identity exists. The method returns false for non-group identities. 
Returns true if a group identity with the specified name exists, false otherwise. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be checked. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCommonExceptions , PPAMINVALIDCREDENTIAL 



8.1.2.10 Method listGroupMembership() 

List the Group Identities the specified Identity is a member of. 

Returns a list of all groups the specified Identity is member of. An empty list is returned if the identity is not member of 
any group. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be looked up. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 
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Returns 
TpPAMFQNameList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1.2.11 Method addAliasO 

Add an alias in the specified namespace to an existing Identity. The alias domain name must be specified in Alias 
parameter. The identity can be a group identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to which the alias will be added. 

alias : in TpPAMFQName 

Specifies the alias to be added. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMALIASEXISTS, PPAMALIASNOTUNIQUE, 
P PAM UNKNOWN IDENTITY, P PAM INVALID CREDENTIAL 



8.1.2.12 Method removeAliases() 

Remove the specified alias from an existing identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity from which the alias will be deleted. 

alias : in TpPAMFQName 

Specifies the alias to be deleted. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, PPAMUNASSIGNEDALIAS, 
P PAM INVALID CREDENTIAL 
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8.1.2.13 Method listAliasesQ 

List the aliases of the specified Identity. 

Returns a list containing all aliases to the specified Identity. A list with zero elements is returned if there are no aliases 
associated with the identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be looked up. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMFQNameList 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 



8.1.2.14 Method lookupByAliasQ 

Find the identity with the specified alias in the specified alias domain. 

Returns the identity that has the specified alias. Returns null if the alias is not assigned to any identity. 

Parameters 

alias : in TpPAMFQName 
Specifies the alias to be looked up. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 

Returns 
TpPAMFQName 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_ALIAS , P_PAM_INVALID_CREDENTIAL 



8.1 .2.15 Method associateTypesQ 

Associate an identity instance with the specified types. The identity will be associated with instances of any attributes 
defined with each type. The initial values of the attributes will be as specified in the definition of the type attributes. 
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Parameters 

identity : in TpPAMFQName 
Specifies the name of the identity. 

identity-Types : in TpStringList 

Specifies the names of the type to be associated. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, P_PAM_UNKNOWN_TYPE, 
P PAM TYPE ASSOCIATED, P PAM INVALID CREDENTIAL 



8.1.2.16 Method disassociateTypesO 

Remove the association of a type with an identity instance. The definition of the type itself remains unaffected and the 
types may continue to be associated with other identities. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity. 

identityTypes : in TpStringList 

Specifies the names of the types to be removed. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, PPAMDISASSOCIATEDTYPE, 
P PAM INVALID CREDENTIAL 



8.1.2.17 Method listTypesOf ldentity() 

List the types associated with the specified Identity. 

Returns a Ust containing all types associated with the specified Identity. A list with zero elements is returned if there are 
no types associated with the identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be looked up. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 
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Returns 
TpPAMFQNameList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1.2.18 Method hasTypeQ 

Check if the specified identity has the named type associated with it. 

Returns true if an identity with the specified name has the named type associated with it, false otherwise. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity to be checked. 

typeName : in TpString 

Specifies the type to be checked for. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.1.2.19 Method getldentityAttributes() 

Return the attributes associated with the identity. If the identity type is not specified, all associated types are assumed to 
be of interest. 

The return value contains the list of specified attributes and their values. If the attributes parameter is an empty array, all 
attributes in the named identity are output. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity whose attributes are to be accessed. 

identityType : in TpString 

Specifies the type of the identity with which the required attributes are associated. Is optional. 

attributeNames : in TpStringList 

List of attributes of interest. Can be an empty array. 
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authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMAttributeList 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, PPAMUNKNOWNTYPE, 
P PAM UNKNOWN ATTRIBUTE, P PAM INVALID CREDENTIAL 



8.1 .2.20 Method setldentityAttributes() 

Modify the attributes associated with the named Identity. The input may contain a subset of the attributes of the named 
type. Only the specified attributes will be modified and the rest will remain unchanged. If the type is unspecified, any 
associated type will be assumed. 

Parameters 

identity : in TpPAMFQName 

Specifies the Identity. 

identity-Type : in TpString 

Specifies the type of the identity for the operation. Is optional. 

attributes : in TpPAMAttributeList 

Contains the list of attributes and their values. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, P_PAM_UNKNOWN_TYPE, 
P PAM UNKNOWN ATTRIBUTES, P PAM INVALID CREDENTIAL 



8.1 .3 Interface Class IpPAMAgentManagement 

Inherits from: Iplnterface. 

The purpose of this interface is to manage agent (that models a hardware or software device) names, communication 
capabilities and sets of attributes associated with agents. An implementation may map these methods to operations on 
existing directories or databases. Some implementations may choose to provide a read-only access to the agent 
information. 

Data associated with an agent is captured in attributes associated with types. An implementation may map different 
type attributes to different underlying stores or directories. 

The names of agents within a namespace must be unique. 

This interface is meant for use by provisioning applications that establish and maintain agent names. 
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«lnterface» 
IpPAMAgentManagement 



createAgent (agentName : in TpPAMFQName, agentTypes : in TpStringList, autin Token : in 
TpPAMCredential) : void 

deleteAgent (agentName : in TpPAMFQName, autin Token : in TpPAMCredential) : void 

isAgent (agentName : in TpPAMFQName, autiiToken : in TpPAMCredential) : TpBoolean 

enableCapabilities (agentName : in TpPAMFQName, capabilities : in TpPAMCapabilityList, authToken : in 
TpPAMCredential) : void 

disableCapabilities (agentName : in TpPAMFQName, capabilities : in TpPAMCapabilityList, authToken : in 
TpPAMCredential) : void 

listEnabledCapabilities (agentName : in TpPAMFQName, authToken : in TpPAMCredential) : 
TpPAMCapabilityList 

listAIICapabilities (agentName : in TpPAMFQName, authToken : in TpPAMCredential) : 
TpPAMCapabilityList 

IsCapableQf (agentName : in TpPAMFQName, capability : in TpPAMCapability, authToken : in 
TpPAMCredential) : TpBoolean 

associateTypes (agentName : in TpPAMFQName, agentTypes : in TpStringList, authToken : in 
TpPAMCredential) : void 

disassociateTypes (agentName : in TpPAMFQName, agentTypes : in TpStringList, authToken : in 
TpPAMCredential) : void 

listTypesQfAgent (agentName : in TpPAMFQName, authToken : in TpPAMCredential) : TpStringList 

hasType (agentName : in TpPAMFQName, typeName : in TpString, authToken : in TpPAMCredential) : 
TpBoolean 

getAgentAttributes (agentName : in TpPAMFQName, agentType : in TpString, attributeNames : in 
TpStringList, authToken : in TpPAMCredential) : TpPAMAttributeList 

setAgentAttributes (agentName : in TpPAMFQName, agentType : in TpString, attributes : in 
TpPAMAttributeList, authToken : in TpPAMCredential) : void 



8.1.3.1 Method createAgentO 

Create an agent initialized with the speciiied capabilities. 

Parameters 

agentName : in TpPAMFQName 

Specifies the name of Agent to be created. 

agentTypes : in TpStringList 

Specifies the types of the Agent to be created. Can be an empty list. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Raises 

TpCoirmonExceptions, PPAMAGENTEXISTS, PPAMUNKNOWNTYPE, 
P PAM INVALID CREDENTIAL 



8.1 .3.2 Method deleteAgentQ 

Delete the specified Agent and all related data from the system. 

Parameters 

agentName : in TpPAMFQName 

Specifies the name of Agent to be created. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNAGENT , P PAMINVALIDCREDENTIAL 



8.1.3.3 Method isAgentO 

Check if the specified agent exists. 

Returns true if an agent with the specified name exists, false otherwise. 

Parameters 

agentName : in TpPAMFQName 

Specifies the Agent to be checked. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCommonExceptions , P_PAMINVALID_CREDENTIAL 



8.1.3.4 Method enableCapabilities() 

Enable the specified capabilities of the agent. 
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Parameters 

agentName : in TpPAMFQName 

Specifies the Agent. 

capabilities : in TpPAMCapabilityList 

Specifies the capabilities to be enabled. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P PAM UNKNOWN AGENT, P PAM INVALID CREDENTIAL 



8.1 .3.5 Method disableCapabilities() 

Remove the specified capabilities from the Agent. 

Parameters 

agentName : in TpPAMFQName 

Specifies the Agent. 

capabilities : in TpPAMCapabilityList 

Specifies the communication mode to be disabled. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNAGENT , PPAMNOCAPABILITY, 
P PAM INVALID CREDENTIAL 



8.1.3.6 Method listEnabledCapabilitiesQ 

List the enabled capabilities for the specified Agent. 

Returns the list of enabled capabilities for the Agent. Returns an empty list if no enabled capabilities exist for the agent. 

Parameters 

agentName : in TpPAMFQName 

Specifies the Agent whose capabilities are to be listed. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Returns 
TpPAMCapabilityList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_INVALID_CREDENTIAL 



8.1.3.7 Method listAIICapabilities() 

List the capabilities for the specified Agent. 

Returns the Ust of capabilities for the Agent. Returns an empty list if no capabilities exist for the agent. 

Parameters 

agentName : in TpPAMFQName 

Specifies the Agent whose capabilities are to be listed. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMCapabilityList 

Raises 

TpCommonExceptions, PPAMUNKNOWNAGENT , PPAMINVALIDCREDENTIAL 



8.1.3.8 Method isCapableOfQ 

Check if an agent has a particular capability that is currently enabled. 
Returns true if the agent has the specified capability, false otherwise. 

Parameters 

agentName : in TpPAMFQName 

Specifies the Agent to be checked. 

capability : in TpPAMCapability 

Capability to be checked. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Returns 
TpBoolean 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , P_PAM_INVALID_CREDENTIAL 



8.1.3.9 Method associateTypesQ 

Associate an agent instance with the specified types. 

Parameters 

agentName : in TpPAMFQName 

Specifies the name of Agent. 

agentTypes : in TpStringList 
Specifies the types of the Agent to be associated. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNAGENT , PPAMUNKNOWNTYPE , 
P PAM TYPE ASSOCIATED, P PAM INVALID CREDENTIAL 



8.1 .3.10 Method disassociateTypesQ 

Remove the association of a type with an agent instance. The definition of the type itself remains unaffected and the 
types may continue to be associated with other agents. 

Parameters 

agentName : in TpPAMFQName 

Specifies the agent. 

agentTypes : in TpStringList 

Specifies the names of the types to be removed. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNAGENT , PPAMDISASSOCIATEDTYPE, 
P PAM INVALID CREDENTIAL 
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8.1 .3.1 1 Method listTypesOfAgent() 

List the types associated with the specified agent. 

Returns the list containing all types associated with the specified agent. An empty list is returned if there are no types 
associated with the agent. 

Parameters 

agentName : in TpPAMFQName 

Specifies the agent to be looked up. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpStringList 

Raises 

TpCommonExceptions, PPAMUNKNOWNAGENT , PPAMINVALIDCREDENTIAL 



8.1.3.12 Method hasTypeO 

Check if the specified agent has the named type associated with it. 

Returns true if an agent with the specified name has the named type associated with it. 

Parameters 

agentName : in TpPAMFQName 

Specifies the Agent to be checked. 

typeName : in TpString 

Specifies the type to be checked for. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_AGENT , PPAMINVALIDCREDENTIAL 



8.1 .3.13 Method getAgentAttributes() 

Return the attributes associated with the agent. If the type is not specified, all associated types are assumed. 
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Return value contains the list of specified attributes and their values. If the attributes parameter is an empty list, all 
attributes in the named agent are returned. 

Parameters 

agentName : in TpPAMFQName 

Specifies the agent. 

agentType : in TpString 

Specifies the type of interest. Is optional. 

attributeNames : in TpStringList 

List of attributes of interest. Can be an empty list. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMAttributeList 

Raises 

TpCommonExc ep t i on s , P_P AMUNKNOWNAGENT , PPAMUNKNOWNTYPE , 
P PAM UNKNOWN ATTRIBUTE, P PAM INVALID CREDENTIAL 



8.1.3.14 Method setAgentAttributesQ 

Modify the attributes associated with the named agent. The input may contain a subset of the attributes of the named 
type. Only the specified attributes will be modified and the rest will remain unchanged. 

Parameters 

agentName : in TpPAMFQName 
Specifies the agent. 

agentType : in TpString 

Specifies the type of interest. Is optional. 

attributes : in TpPAMAttributeList 

Contains the list of attributes and their values. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNAGENT , PPAMUNKNOWNTYPE , 
P PAM UNKNOWN ATTRIBUTES, P PAM INVALID CREDENTIAL 
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8.1 .4 Interface Class IpPAMAgentAssignment 

Inherits from: Iplnterface. 

The purpose of this interface is to manage the relationship between identities and the agents assigned to them. The 
identities inherit capabilities from the assignments of agents. 

The implementation must maintain the integrity of the relationship between identities and agents across changes to 
both identities and agents. Implementations may map these methods to operations on existing directories and databases. 
Some implementations may provide a read-only access to this interface. 

This interface is meant for use by provisioning applications that establish and maintain association of agents with 
identities. 



«lnterface» 
IpPAMAgentAssignment 



assignAgent (identity : in TpPAMFQName, agentName : in TpPAMFQName, authToken : in 
TpPAMCredential) : void 

unassignAgent (identity : in TpPAMFQName, agentName : in TpPAMFQName, autin Token : in 
TpPAMCredential) : void 

listAssignedAgents (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpPAMFQNameList 

listAssociatedldentitiesQfAgent (agentName : in TpPAMFQName, authToken : in TpPAMCredential) : 
TpPAMFQNameList 

listAssignedAgentsByCapability (identity : in TpPAMFQName, capability : in TpPAMCapability, authToken 
in TpPAMCredential) : TpPAMFQNameList 

listCapabilitiesQfldentity (identity : in TpPAMFQName, authToken : in TpPAMCredential) : 
TpPAMCapabilityList 

IsidentityCapableQf (identity : in TpPAMFQName, capability : in TpPAMCapability, authToken : in 
TpPAMCredential) : TpBoolean 



8.1.4.1 Method assignAgentO 

Assign an existing agent to an existing identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity to assign the agent to. 

agentName : in TpPAMFQName 

Specifies the Agent. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 
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Raises 

TpCoirmonExceptions, PPAMUNKNOWNIDENTITY, PPAMUNKNOWNAGENT , 
P PAM INVALID CREDENTIAL 



8.1.4.2 Method unassignAgentO 

Unassign an agent from an existing identity. In effect, this deletes an existing relationship between an agent and an 
identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity to assign the agent to. 

agentName : in TpPAMFQName 

Specifies the Agent. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCoirmonExceptions, PPAMUNKNOWNIDENTITY, PPAMUNKNOWNAGENT , 
P PAM UNKNOWN ASSIGNMENT, P PAM INVALID CREDENTIAL 



8.1.4.3 Method listAssignedAgents() 

List the Agents assigned to an identity. 

Returns the list of agent names assigned to the identity. An empty list is returned if no agents are assigned to the 
identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMFQNameList 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 
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8.1.4.4 Method listAssociatedldentitiesOfAgent() 

List the identities that have the specified agent assigned to them. 

Returns the list of identities that have been assigned the specified agent. Empty list is returned if no identities have been 
assigned this agent. 

Parameters 

agentName : in TpPAMFQName 

Specifies the Agent. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMFQNameList 

Raises 

TpCommonExceptions, PPAMUNKNOWNAGENT , PPAMINVALIDCREDENTIAL 



8.1.4.5 Method listAssignedAgentsByCapabilityO 

List the Agents assigned to an identity that match the specified capability. 

Returns the list of agent names with the specified capability. An empty list is returned no agents are found. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

capability : in TpPAMCapability 
Specifies the capability of interest. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMFQNameList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, PPAMINVALIDCREDENTIAL 



8.1.4.6 Method listCapabilitiesOfldentity() 

List the capabilities of an identity that it derives from its assigned Agents. 

Returns the hst of the identity's capabilities. Returns an empty list if no capabilities exist. 
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Parameters 

identity : in TpPAMFQName 
Specifies the identity of interest. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMCapabilityList 

Raises 

TpCoirmonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 



8.1.4.7 Method isldentityCapableOf() 

Check if an identity has the specified capabihty derived from one or more agents assigned to it. 
Returns true if the identity has this capabihty, false otherwise. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

capability : in TpPAMCapability 

Identifies the capabihty to check for. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCommonExceptions, P PAMUNKNOWNIDENTITY, P PAMINVALIDCREDENTIAL 



8.1 .5 Interface Class IpPAMIdentityTypeManagement 

Inherits from: Iplnterface. 

This clause describes the programmatic interface to define the type schema for identities specifying the attributes 
associated with the type. These types can then be assigned to identities. PAM implementations may provide a set of pre- 
defined types. Identity type names and agent type names are in the same namespace and hence must be uniquely 
defined across both identities and agents. The attributes for identity types and agent types are in two different 
namespaces and hence an attribute name may be re-used with different characteristics for identities and agents. 
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«lnterface» 
IpPAMIdentityTypeManagement 



createldentityAttribute (pAttribute : in TpPAMAttributeDef, authToken : in TpPAMCredential) : void 

deleteldentityAttribute (attributeName : in TpString, autin Token : in TpPAMCredential) : void 

getldentityAttributeDefinition (attributeName : in TpString, autiiToken : in TpPAMCredential) : 
TpPAMAttributeDef 

listAII Identity Attributes (authToken : in TpPAMCredential) : TpStringList 

createldentityType (typeName : in TpString, attributeNames : in TpStringList, authToken : in 
TpPAMCredential) : void 

deleteldentityType (typeName : in TpString, authToken : in TpPAMCredential) : void 

listldentity Types (authToken : in TpPAMCredential) : TpStringList 

addldentityTypeAttributes (typeName : in TpString, attributeNames : in TpStringList, authToken : in 
TpPAMCredential) : void 

removeldentityTypeAttributes (typeName : in TpString, attributeNames : in TpStringList, authToken : in 
TpPAMCredential) : void 

listldentityTypeAttributes (typeName : in TpString, authToken : in TpPAMCredential) : TpStringList 



8.1.5.1 Method createldentityAttribute() 

Create a definition of an identity attribute to specify its name and type. 

Parameters 

pAttribute : in TpPAMAttributeDef 

Specifies the attribute to be created. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_ATTRIBUTE_EXISTS, PPAMINVALIDCREDENTIAL 



8.1 .5.2 Method deleteldentityAttributeQ 

Delete the definition of an identity attribute. 

Parameters 

attributeName : in TpString 

Specifies the attribute to be deleted. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 
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Raises 

TpCoirmonExceptions , PPAMUNKNOWNATTRIBUTE , PPAMINVALIDCREDENTIAL 



8.1 .5.3 Method getldentityAttributeDefinitionQ 

Get the definition for the specified identity attribute. 
Returns the definition of the specified attribute. 

Parameters 

attributeName : in TpString 

Specifies the attribute. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Returns 
TpPAMAttributeDef 

Raises 

TpCoirmonExceptions , PPAMUNKNOWNATTRIBUTE , PPAMINVALIDCREDENTIAL 



8.1.5.4 Method listAllldentityAttributes() 

List all known identity attributes. 

Returns the list of attribute names defined so far. An empty array if no attributes have been defined. 

Parameters 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Returns 
TpStringList 

Raises 

TpCoirmonExceptions , PPAMINVALIDCREDENTIAL 



8.1.5.5 Method createldentityType() 

Specify a label as the name of an identity type. 
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Parameters 

typeName : in TpString 

Specifies the name of the type to be created. 

attributeNames : in TpStringList 
Specifies the hst of attributes to be added. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_TYPE_EXISTS, P_PAM_UNKNOWN_ATTRIBUTE, 
P PAM INVALID CREDENTIAL 



8.1 .5.6 Method deleteldentityType() 

Delete a label as the name of an identity type. All identities that have this type are no longer associated with this type 
and consequently will no longer will have any attributes associated with this type. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNTYPE, PPAMINVALIDCREDENTIAL 



8.1.5.7 Method listldentityTypes() 

List all known identity types. 

Returns the list of known identity types. An empty array if no identity types have been defined. 

Parameters 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 
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Returns 
TpStringList 

Raises 

TpCoinmonExceptions , P_PAM_INVALID_CREDENTIAL 



8.1.5.8 Method addldentityTypeAttributes() 

Add attribute definitions to the schema of an identity type that has already been defined. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

attributeNames : in TpStringList 

List of attributes to be added to this type. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCoirmonExceptions, PPAMUNKNOWNTYPE, PPAMATTRIBUTEEXISTS, 
P PAM UNKNOWN ATTRIBUTE, P PAM INVALID CREDENTIAL 



8.1.5.9 Method removeldentityTypeAttributes() 

Delete attribute definitions from the schema of an identity type that has already been defined. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

attributeNames : in TpStringList 
Specifies the list of attributes to be deleted. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNTYPE, PPAMUNKNOWNATTRIBUTE, 
P PAM INVALID CREDENTIAL 
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8.1.5.10 Method listldentityTypeAttributes() 

List all attributes of an identity type. 

Returns the list of attribute definitions for the named type. An empty array if no attributes have been defined for this 
type. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Returns 
TpStringList 

Raises 

TpCommonExceptions, PPAMUNKNOWNTYPE, PPAMINVALIDCREDENTIAL 



8.1 .6 Interface Class IpPAMAgentTypeManagement 

Inherits from: Iplnterface. 

This clause describes the programmatic interface to define the type schema for agents specifying the attributes 
associated with the type. These types can then be assigned to agents. PAM implementations may provide a set of pre- 
defined types. Identity type names and agent type names are in the same namespace and hence must be uniquely 
defined across both identities and agents. The attributes for identity types and agent types are in two different 
namespaces and hence an attribute name may be re-used with different characteristics for identities and agents. 
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«lnterface» 
IpPAMAgentTypeManagement 



createAgentAttribute (pAttribute : in TpPAMAttributeDef, authToken : in TpPAMCredential) : void 

deleteAgentAttribute (attributeName : in TpString, autin Token : in TpPAMCredential) : void 

getAgentAttributeDefinition (attributeName : in TpString, autin Token : in TpPAMCredential) : 
TpPAMAttributeDef 

listAIIAgentAttributes (authToken : in TpPAMCredential) : TpStringList 

createAgentType (typeName : in TpString, attributeNames : in TpStringList, authToken : in 
TpPAMCredential) : void 

deleteAgentType (typeName : in TpString, authToken : in TpPAMCredential) : void 

listAgentTypes (authToken : in TpPAMCredential) : TpStringList 

addAgentTypeAttributes (typeName : in TpString, attributeNames : in TpStringList, authToken : in 
TpPAMCredential) : void 

removeAgentTypeAttributes (typeName : in TpString, attributeNames : in TpStringList, authToken : in 
TpPAMCredential) : void 

listAgentTypeAttributes (typeName : in TpString, authToken : in TpPAMCredential) : TpStringList 



8.1.6.1 Method createAgentAttribute() 

Create a definition of an Agent attribute to specify its name and type. 

Parameters 

pAttribute : in TpPAMAttributeDef 

Specifies the attribute to be created. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_ATTRIBUTE_EXISTS, PPAMINVALIDCREDENTIAL 



8.1.6.2 Method deleteAgentAttribute() 

Delete the definition of an Agent attribute. 

Parameters 

attributeName : in TpString 

Specifies the attribute to be deleted. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 
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Raises 

TpCoirmonExceptions , PPAMUNKNOWNATTRIBUTE , PPAMINVALIDCREDENTIAL 



8.1 .6.3 Method getAgentAttributeDefinition() 

Get the definition for the specified Agent attribute. 
Returns the definition of the specified attribute. 

Parameters 

attributeName : in TpString 

Specifies the attribute. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Returns 
TpPAMAttributeDef 

Raises 

TpCoirmonExceptions , PPAMUNKNOWNATTRIBUTE , PPAMINVALIDCREDENTIAL 



8.1.6.4 Method listAIIAgentAttributes() 

List all known Agent attributes. 

Returns the list of attribute names defined so far. An empty array if no attributes have been defined. 

Parameters 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Returns 
TpStringList 

Raises 

TpCoirmonExceptions , PPAMINVALIDCREDENTIAL 



8.1 .6.5 Method createAgentType() 

Specify a label as the name of an Agent type. 
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Parameters 

typeName : in TpString 

Specifies the name of the type to be created. 

attributeNames : in TpStringList 
Specifies the hst of attributes to be added. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_TYPE_EXISTS, P_PAM_UNKNOWN_ATTRIBUTE, 
P PAM INVALID CREDENTIAL 



8.1 .6.6 Method deleteAgentTypeQ 

Delete a label as the name of an Agent type. All identities that have this type are no longer associated with this type and 
consequently will no longer will have any attributes associated with this type. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNTYPE, PPAMINVALIDCREDENTIAL 



8.1.6.7 Method listAgentTypesO 

List all known Agent types. 

Returns the list of known Agent types. An empty array if no Agent types have been defined. 

Parameters 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 
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Returns 
TpStringList 

Raises 

TpCoinmonExceptions , P_PAM_INVALID_CREDENTIAL 



8.1 .6.8 Method addAgentTypeAttributes() 

Add attribute definitions to the schema of an Agent type that has already been defined. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

attributeNames : in TpStringList 

List of attributes to be added to this type. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCoirmonExceptions, PPAMUNKNOWNTYPE, PPAMATTRIBUTEEXISTS, 
P PAM UNKNOWN ATTRIBUTE, P PAM INVALID CREDENTIAL 



8.1.6.9 Method removeAgentTypeAttributes() 

Delete attribute definitions from the schema of an Agent type that has already been defined. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

attributeNames : in TpStringList 
Specifies the list of attributes to be deleted. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNTYPE, PPAMUNKNOWNATTRIBUTE, 
P PAM INVALID CREDENTIAL 
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8.1.6.10 Method listAgentTypeAttributes() 

List all attributes of an Agent type. 

Returns the list of attributes for the named type. An empty array if no attributes have been defined for this type. 

Parameters 

typeName : in TpString 

Specifies the name of the type. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Returns 
TpStringList 

Raises 

TpCommonExceptions, P PAMUNKNOWNTYPE, P PAMINVALIDCREDENTIAL 



8.1 .7 Interface Class IpPAMCapabilityManagement 

Inherits from: Iplnterface. 

This clause describes the programmatic interface to define capability names. 

Capabilities are names that define a property of an agent for which presence data may exist. Examples are voice, IM, 
SMS, WAP, etc. Agents can be assigned capabilities. Identities inherit capabilities from agents but cannot be directly 
assigned capabilities. Each capability is defined with an associated set of attributes. The attributes for each capability 
exist in their own namespace and hence an attribute name may be re-used with different characteristics across 
capabilities. 
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«lnterface» 
IpPAMCapabilityManagement 



createCapabilityAttribute (pAttribute : in TpPAMAttributeDef, authToken : in TpPAMCredential) : void 

deleteCapabilityAttribute (attributeName : in TpString, autiiToken : in TpPAMCredential) : void 

getCapabilityAttributeDefinition (attributeName : in TpString, autliToken : in TpPAMCredential) : 
TpPAMAttributeDef 

listAIICapabilityAttributes (authToken : in TpPAMCredential) : TpStringList 

createCapability (capabilityName : in TpPAMCapability, attributeNames : in TpStringList, authToken : in 
TpPAMCredential) : void 

deleteCapability (capabilityName : in TpPAMCapability, authToken : in TpPAMCredential) : void 

listCapabilities (authToken : in TpPAMCredential) : TpPAMCapabilityList 

addCapabilityAttributes (capabilityName : in TpPAMCapability, attributeNames : in TpStringList, authToken : 
in TpPAMCredential) : void 

removeCapabilityAttributes (capabilityName : in TpPAMCapability, attributeNames : in TpStringList, 
authToken : in TpPAMCredential) : void 

listCapabilityAttributes (capabilityName : in TpPAMCapability, authToken : in TpPAMCredential) : 
TpStringList 

assignCapabilitiesToType (agentType : in TpString, capabilities : in TpPAMCapabilityList, authToken : in 
TpPAMCredential) : void 

unassignCapabilitiesFromType (agentType : in TpString, capabilities : in TpPAMCapabilityList, authToken : 
in TpPAMCredential) : void 

listCapabilitiesOfType (agentType : in TpString, authToken : in TpPAMCredential) : TpPAMCapabilityList 



8.1.7.1 Method createCapability Attribute() 

Create a definition of a Capability attribute to specify its name and type. 

Parameters 

pAttribute : in TpPAMAttributeDef 

Specifies the attribute to be created. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCoirmonExceptions , P_PAM_ATTRIBUTE_EXISTS , P_PAM_INVALID_CREDENTIAL 



8.1 .7.2 Method deleteCapabilityAttribute() 

Delete the definition of a Capability attribute. 
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Parameters 

attributeName : in TpString 

Specifies the attribute to be deleted. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCoinmonExceptions , PPAMUNKNOWNATTRIBUTE , PPAMINVALIDCREDENTIAL 



8.1 .7.3 Method getCapabilityAttributeDefinition() 

Get the definition for the specified Capability attribute. 
Returns the definition of the specified attribute. 

Parameters 

attributeName : in TpString 

Specifies the attribute. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Returns 
TpPAMAttributeDef 

Raises 

TpCoinmonExceptions , P_PAM_UNKNOWN_ATTRIBUTE , PPAMINVALIDCREDENTIAL 



8.1.7.4 Method listAIICapabilityAttributes() 

List all known Capability attributes. 

Returns the list of attribute names defined so far. An empty array if no attributes have been defined. 

Parameters 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 
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Returns 
TpStringList 

Raises 

TpCoinmonExceptions , P_PAM_INVALID_CREDENTIAL 



8.1.7.5 Method createCapabilityO 

Specify a label as the name of a Capability type. 

Parameters 

capabilityName : in TpPAMCapability 

Specifies the name of the type to be created. 

attributeNames : in TpStringList 
Specifies the list of attributes to be added. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCoirmonExceptions, PPAMTYPEEXISTS, PPAMUNKNOWNATTRIBUTE, 
P PAM INVALID CREDENTIAL 



8.1 .7.6 Method deleteCapability() 

Delete a label as the name of a Capability. All agents that have this type are no longer associated with this type and 
consequently will no longer will have any attributes associated with this type. 

Parameters 

capabilityName : in TpPAMCapability 

Specifies the name of the type. 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Raises 

TpCoinmonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_INVALID_CREDENTIAL 



8.1.7.7 Method listCapabilitiesQ 

List all known Capability types. 
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Returns the list of known Capability types. An empty array if no Capability types have been defined. 

Parameters 

authToken : in TpPAMCredential 

Credential of the entity who wishes to do this operation. 

Returns 
TpPAMCapabilityList 

Raises 

TpCoimnonExceptions , P_PAM_INVALID_CREDENTIAL 



8.1.7.8 Method addCapabilityAttributes() 

Add attribute definitions to the schema of a capability that has already been defined. 

Parameters 

capabilityName : in TpPAMCapability 
Specifies the name of the type. 

attributeNames : in TpStringList 

List of attributes to be added to this type. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCoimnonExceptions, PPAMUNKNOWNTYPE, PPAMATTRIBUTEEXISTS, 
P PAM UNKNOWN ATTRIBUTE, P PAM INVALID CREDENTIAL 



8.1.7.9 Method removeCapabilityAttributes() 

Delete attribute definitions from the schema of a Capability that has already been defined. 

Parameters 

capabilityName : in TpPAMCapability 

Specifies the name of the type. 

attributeNames : in TpStringList 
Specifies the list of attributes to be deleted. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 
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Raises 

TpCoirmonExceptions, PPAMUNKNOWNTYPE, PPAMUNKNOWNATTRIBUTE, 
P PAM INVALID CREDENTIAL 



8.1.7.10 Method listCapabilityAttributes() 

List all attributes of a capability. 

Returns the list of attributes for the named Capability. An empty array if no attributes have been defined for this 
capability. 

Parameters 

capabilityName : in TpPAMCapability 

Specifies the name of the type. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Returns 
TpStringList 

Raises 

TpCommonExceptions, PPAMUNKNOWNTYPE, PPAMINVALIDCREDENTIAL 



8.1 .7.1 1 Method assignCapabilitiesToType() 

Assign capabilities to agent type. 

Parameters 

agentType : in TpString 
Name of an agent type. 

capabilities : in TpPAMCapabilityList 

Specifies the list of capabilities to be associated. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_UNKNOWN_CAPABILITY, 
P PAM INVALID CREDENTIAL 
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8.1.7.12 Method unassignCapabilitiesFromType() 

Unassign capabilities from an agent type. 

Parameters 

agentType : in TpString 

Name of an agent type. 

capabilities : in TpPAMCapabilityList 

Specifies the list of capabilities to be disassociated. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCoinmonExceptions, PPAMUNKNOWNTYPE, PPAMUNKNOWNCAPABILITY, 
P PAM INVALID CREDENTIAL 



8.1.7.13 Method listCapabilitiesOfType() 

List capabilities assigned to an agent type. 

Returns the hst of capabilities assigned to the agent type. 

Parameters 

agentType : in TpString 

Name of an agent type. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 

Returns 
TpPAMCapabilityList 

Raises 

TpCoinmonExceptions, P_PAM_UNKNOWN_TYPE, P_PAM_INVALID_CREDENTIAL 

8.2 PAM Access SCF Interface Classes 

This service consists of the presence and availability query and update interfaces. 

8.2.1 Interface Class IpPAMPresenceAvailabilityManager 

Inherits from: IpService. 

The purpose of this interface is to supply the various interfaces available in this service to the application and to provide 
the authentication credentials. This interface is the only discoverable interface from the framework. 

All PAM methods optionally use an authentication token as a parameter since the outcome of the operations may 
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depend on the entity requesting the operation. To enable this, the getAuthToken() method is used to obtain an 
implementation dependent token. An application that has authenticated itself with the OS A framework, can get an 
authentication token for itself Alternatively, if the application is requesting PAM operations on behalf of multiple 
entities, authentication tokens may be requested for each such entity after providing any available data about the asker. 
These tokens can then be used repeatedly for operations within a session without further need to identify the asker. 



«lnterface» 
IpPAMPresenceAvailabilityManager 



getAuthloken (askerData : in TpAttributeList) : TpPAMCredential 

obtainlnterface (interfaceName : in TpPAMPresenceAvailabilitylnterfaceName) : IplnterfaceRef 

getAccessControl (identity : in TpPAMFQName, autin Token : in TpPAMCredential) : 
TpPAMAccessControlData 

setAccessControl (identity : in TpPAMFQName, operation : in TpPAMPreferenceOp, newAccessControl : in 
TpPAMAccessControlData, authToken : in TpPAMCredential) : void 

activateService (identity : in TpPAMFQName, authToken : in TpPAMCredential) : void 

deactivateService (identity : in TpPAMFQName, authToken : in TpPAMCredential) : void 

isActiveldentity (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpBoolean 



8.2.1 .1 Method getAuthloken () 

Get an authentication token for access to the interface methods. 

Returns an implementation-dependent authentication credential that can be verified. 

Parameters 

askerData : in TpAttributeList 

Specifies information about the asker. Can be an empty array. The exact attributes in this list are dependent on the 
application. PAM reserves the attribute "name" with type TpPAMFQName to contain the identity of the asker if known. 

Returns 
TpPAMCredential 

Raises 

TpCoinmonExceptions , PPAMINVALIDCREDENTIAL 



8.2.1.2 Method obtain InterfaceO 

Obtain available interfaces from the service. The valid parameters for this method can be obtained from the service 
property P_OBTAIN ABLE_INTERFACES . 

Returns the requested interface. 
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Parameters 

interfaceName : in TpPAMPresenceAvailabilitylnterfaceName 
Specifies the name of the required interface. 

Returns 
IpInterfaceRef 

Raises 

TpCommonExceptions , PPAMUNAVAILABLEINTERFACE 

8.2.1 .3 Method getAccessControlQ 

Get the access control associated with the data belonging to an identity. The data associated with an identity includes 
the static and dynamic attributes of an identity as well as data about agents associated with an identity. 

This method should be used in conjunction with the setAccessControl method. 

Returns the access control if previously specified for the identity. Is null if there is no access control associated. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMAccessControlData 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 



8.2.1.4 Method setAccessControlO 

Set the access controls for the data associated with the specified identity. If the identity is Null, the access control is set 
for all identities (if authorized to do so). The data associated with an identity includes the static and dynamic attributes 
of an identity as well as data about agents associated with an identity. 

Any existing access control will be modified based on the operation. 

If the new access control is specified as Null for replace operation , an existing access control will be removed. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

operation : in TpPAMPreferenceOp 

Specifies the operation to be performed with the specified preference. 
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newAccessControl : in TpPAMAccessControlData 

Specifies the access controls to add. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 



8.2.1.5 Method activateServiceO 

Activate the service for the specified identity. If the identity is null, activate the service for ALL identities. The method 
succeeds if the service is already activated for the specified identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. Can be NULL (empty string). 

authToken : in TpPAMCredential 

of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.2.1 .6 Method deactivateService() 

Deactivate the service for the specified identity. If the identity is null, deactivate the service for ALL identities. The 
method succeeds if the service is already deactivated for the specified identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. Can be NULL (empty string). 

authToken : in TpPAMCredential 
of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 



8.2.1.7 Method isActiveldentityO 

Check if the service is active for the specified identity. 

Returns true if the service is active for that identity, false otherwise. 
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Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. Cannot be NULL (empty string). 

authToken : in TpPAMCredential 

of the entity who wishes to do this operation. 

Returns 
TpBoolean 

Raises 

TpCoirmonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 



8.2.2 Interface Class IpPAMIdentityPresence 

Inherits from: Iplnterface. 

The purpose of this interface is to maintain the dynamic presence information of identity. 

The underlying implementations may optimize the storage for this dynamic data rather than rely on a general- 
purpose directory or database when performance is an issue. Presence information for identities may be explicitly 
registered are may be implicitly derived from the underlying networks or presence information from agents associated 
with the identity. 

This interface is meant for use by applications that register and/or maintain dynamic presence information 
associated with identities and accessible without the privacy or other controls established by availability preferences. 
These applications may not be aware of the name and the types of agents associated with the identity. 

The presence information can be explicitly registered using the interface or the presence may come from 
information implicitly derived (e.g., using presence information of agents associated with the identity). 



«lnterface» 
IpPAMIdentityPresence 



setldentityPresence (identity : in TpPAMFQName, identityType : in TpString, attributes : in 
TpPAMAttributeList, autiiToken : in TpPAMCredential) : void 

setldentityPresenceExpiration (identity : in TpPAMFQName, identityType : in TpString, attributeNames : in 
TpStringList, expiresin : in TpPAMTimelnterval, authToken : in TpPAMCredential) : void 

getldentityPresence (identity : in TpPAMFQName, identityType : in TpString, attributeNames : in 
TpStringList, authToken : in TpPAMCredential) : TpPAMAttributeList 



8.2.2.1 Method setldentityPresence() 

Set identity's dynamic attributes. 



ETSI 



3GPP TS 29.1 98-1 4 version 9.0.0 Release 9 71 ETSI TS 1 29 1 98-1 4 V9.0.0 (201 0-01 ) 

Parameters 

identity : in TpPAMFQName 
Specifies the identity. 

identity-Type : in TpString 
Specifies the type of the identity. 

attributes : in TpPAMAttributeList 

Specifies the attributes to set. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCoirmonExceptions, PPAMUNKNOWNIDENTITY, PPAMUNKNOWNTYPE, 
P PAM UNKNOWN ATTRIBUTE, P PAM INVALID CREDENTIAL 



8.2.2.2 Method setldentityPresenceExpiration() 

Set or reset the expiration of an identity's named presence attributes. If the attributeNames parameter is an empty Hst, 
the expiration time of all attributes defined for the identity will have their expiration time changed. 

Parameters 

identity : in TpPAMFQName 
Specifies the identity. 

identityType : in TpString 
Specifies the type of the identity. 

attributeNames : in TpStringList 

Specifies the names of the attributes. Can be an empty list. 

expiresin : in TpPAMTime Interval 

Specifies the number of seconds until the attributes expire. A value of -1 indicates no expiration. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, PPAMUNKNOWNTYPE, 
P PAM UNKNOWN ATTRIBUTE, P PAM INVALID CREDENTIAL 



8.2.2.3 Method getldentityPresenceQ 

Retrieve presence attributes associated with an identity. 
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Return value contains the requested attributes of the named capability. If the attributes parameter is an empty array, all 
attributes of the named profile are included. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity. 

identity-Type : in TpString 
Specifies the type of the identity. 

attributeNames : in TpStringList 

Specifies the attributes of interest. Can be an empty list. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMAttributeList 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, PPAMUNKNOWNTYPE, 
P PAM UNKNOWN ATTRIBUTE, P PAM INVALID CREDENTIAL 



8.2.3 Interface Class IpPAMAvailability 

Inherits from: Iplnterface. 

The purpose of the interface is to: 

- Manage the preferences specified for the availability of an identity and, to 

- Query for the availability of identities for specific capabilities. 

- Query for attributes of interest from an identity. 

Simple implementations may equate the availability of identities to presence of their agents with available 
status. More complex implementations may consider, in addition, the preferences specified for availability as well as the 
attributes of the entity asking for availability. 

The queries for availability are done for a specified context. A context is a set of attributes describing the situation 
for which availability is requested. PAM specifies one pre-defined context - Communication. The Communication 
context is used for availability for a specific mode of communication. Applications and PAM implementations may 
extend and provide additional contexts such as availability at a particular location, availability for a specific mode of 
communication at a given location, etc. The context information also includes any information about the asker as may 
be provided by the asker. 

The specification defines two types of preference mechanisms although implementations may support additional 
mechanisms. The first mechanism consists of access control lists that specify identities that are allowed/denied to access 
information about the identity whose preference is being set. The second mechanism allow for an external application 
interface to be specified to check for access control as well as to compute availability. 
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«lnterface» 
IpPAMAvailability 



getAvailability (identity : in TpPAMFQName, pamContext : in TpPAMContext, attributeNames : in 
TpStringList, autin Token : in TpPAMCredential) : TpPAMAvailabilityProfileList 

getPreference (identity : in TpPAMFQName, pamContext : in TpPAMContext, autin Token : in 
TpPAMCredential) : TpPAMPreferenceData 

setPreference (identity : in TpPAMFQName, pamContext : in TpPAMContext, operation : in 

TpPAMPreferenceQp, newPreference : in TpPAMPreferenceData, autin Token : in TpPAMCredential) 
void 



8.2.3.1 Method getAvailability() 

Get the availability for an identity for a given context. 

All contexts may optionally include an asker profile. Although PAM applications may decide what attributes to include 
in an asker profile, PAM implementations should not require such attributes to be present. The implementations should 
leave it to the availability computations to decide the availability based on the (partial) information provided. 

It is also up to the availability computation to decide on the trustworthiness of the asker profile information based on the 
application, the credentials of the entity asking for availability and/or the credentials, if any, of the entity accessing the 
interface. 

Returns a value containing a list of attributes as available to the asker in the requested context. If no information is 
available to the asker an empty list is returned. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity for which the availability is being requested. 

pamContext : in TpPAMContext 

Specifies the context for which the availability is requested. 

attributeNames : in TpStringList 

Specifies the attributes of interest. Can be an empty list to indicate all attributes. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 

Returns 
TpPAMAvailabilityProfileList 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 
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8.2.3.2 Method getPreference() 

Get the availability preferences of an identity for the specified communication mode. 

This method should be used in conjunction with the setPreference method. 

Returns the preference for the named context if previously specified for the identity. Is null if there are no preferences 
associated. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. 

pamContext : in TpPAMContext 

Specifies the context for which the preferences are requested. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMPreferenceData 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 



8.2.3.3 Method setPreferenceQ 

Set the availability preferences for the specified identity for the specified context. If the identity is Null, the preference 
is set for all identities (if authorized to do so). 

The existing preference will be modified based on the operation. 

If the new preference is specified as Null for replace operation , any existing preferences for the specified context will 
be removed. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity with which the preference will be associated. 

pamContext : in TpPAMContext 
Specifies the capability to which this preference applies. 

operation : in TpPAMPreferenceOp 

Specifies the operation to be performed with the specified preference. 

newPref erence : in TpPAMPreferenceData 

Specifies the availability preference to add. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 
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Raises 

TpCoirmonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 

8.2.4 Interface Class IpPAMAgentPresence 

Inherits from: Iplnterface. 

The purpose of this interface is to maintain the dynamic presence information of agents. 

The underlying implementations may optimize the storage for this dynamic data rather than rely on a general- 
purpose directory or database when performance is an issue. Agents may explicitly register the presence information or 
the presence information may be implicitly derived from the underlying networks. 

The presence information is modelled through dynamic attributes. Sets of dynamic attributes can be defined per 
agent type (e.g. agent location, power status) or per agent capability (e.g. agent status for voice/messaging, 
communication address). 

This interface is meant for use by applications that query and update agent presence information directly regardless 
of the identities to which the agent is assigned. 



«lnterface» 
IpPAMAgentPresence 



setAgentPresence (agent : in TpPAMFQName, agentType : in TpString, attributes : in TpPAMAttributeList, 
autinToken : in TpPAMCredential) : void 

setCapabilityPresence (agent : in TpPAMFQName, capability : in TpPAMCapability, attributes : in 
TpPAMAttributeList, authToken : in TpPAMCredential) : void 

setAgentPresenceExpiration (agent : in TpPAMFQName, agentType : in TpString, attributeNames : in 
TpStringList, expiresin : in TpPAMTimelnterval, authToken : in TpPAMCredential) : void 

setCapabilityPresenceExpiration (agent : in TpPAMFQName, capability : in TpPAMCapability, 

attributeNames : in TpStringList, expiresin : in TpPAMTimelnterval, authToken : in TpPAMCredential) : 
void 

getAgentPresence (agent : in TpPAMFQName, agentType : in TpString, attributeNames : in TpStringList, 
authToken : in TpPAMCredential) : TpPAMAttributeList 

getCapabilityPresence (agent : in TpPAMFQName, capability : in TpPAMCapability, attributeNames : in 
TpStringList, authToken : in TpPAMCredential) : TpPAMAttributeList 



8.2.4.1 Method setAgentPresenceQ 

Set presence attribute values for an agent. 

Parameters 

agent : in TpPAMFQName 

Specifies the agent. 

agentType : in TpString 
Specifies the type of the agent. 

attributes : in TpPAMAttributeList 

Specifies the dynamic attributes to set. 
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authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExc ep t i on s , P_P AMUNKNOWNAGENT , P_PAM_UNKNOWN_TYPE , 
PPAMUNKNOWNATTRIBUTE , PPAMINVALIDCREDENTIAL 

8.2.4.2 Method setCapabilityPresence() 

Set presence attribute values for a set of capabiUties of an agent. 

Parameters 

agent : in TpPAMFQName 
Specifies the agent. 

capability : in TpPAMCapability 
Specifies which capability of the agent to set. 

attributes : in TpPAMAttributeList 

Specifies the dynamic attributes to set. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMUNKNOWNAGENT , PPAMUNKNOWNCAPABILITY, 
PPAMUNKNOWNATTRIBUTE , PPAMINVALIDCREDENTIAL 

8.2.4.3 Method setAgentPresenceExpirationQ 

Set or reset the expiration of an agent's named presence profile. 

Parameters 

agent : in TpPAMFQName 

Specifies the agent. 

agentType : in TpString 

Specifies the type of the agent. 

attributeNames : in TpStringList 

Specifies the names of the dynamic attributes. May be an empty array to indicate all dynamic attributes are to be 
affected. 

expires In : in TpPAMTimelnterval 

Specifies the number of seconds until the attributes expire. A value of -1 indicates no expiration. A value of indicates 
immediate expiration. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Raises 

TpCoirmonExc ep t i on s , P_P AMUNKNOWNAGENT , PPAMUNKNOWNTYPE , 
PPAMUNKNOWNATTRIBUTE , PPAMINVALIDCREDENTIAL 

8.2.4.4 Method setCapabilityPresenceExpiration() 

Set or reset the expiration of named presence attributes for a set of capabilities of an agent. 

Parameters 

agent : in TpPAMFQName 

Specifies the agent. 

capability : in TpPAMCapability 
Specifies the type of the agent. 

attributeNames : in TpStringList 

Specifies the names of the dynamic attributes. May be an empty array to indicate all dynamic attributes are to be 
affected. 

expiresin : in TpPAMTimelnterval 

Specifies the number of seconds until the attributes expire. A value of -1 indicates no expiration. A value of indicates 
immediate expiration. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Raises 

TpCoirmonExc ept ions, PPAMUNKNOWNAGENT , PPAMNOCAPABILITY, 
PPAMUNKNOWNATTRIBUTE , P_PAM_INVALID_CREDENTIAL 

8.2.4.5 Method getAgentPresence() 

Retrieve named presence attributes for an agent. 

Return value contains the requested dynamic attributes associated with the specified agent. If the attributeNames 
parameter is an empty list, all dynamic attributes of the specified agent are included. 

Parameters 

agent : in TpPAMFQName 

Specifies the agent. 

agentType : in TpString 

Specifies the type of the agent. 

attributeNames : in TpStringList 

Specifies the dynamic attributes of interest. Can be an empty array to indicate all dynamic attributes are to be retrieved. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Returns 
TpPAMAttributeList 

Raises 

TpCoirmonExc ep t i on s , P_P AMUNKNOWNAGENT , P_PAM_UNKNOWN_TYPE , 
PPAMUNKNOWNATTRIBUTE , PPAMINVALIDCREDENTIAL 

8.2.4.6 Method getCapabilityPresence() 

Retrieve named presence attributes for a capability of an agent. 

Return value contains the requested dynamic attributes associated with the specified agent. If the attributeNames 
parameter is an empty list, all dynamic attributes of the specified agent are included. 

Parameters 

agent : in TpPAMFQName 

Specifies the agent. 

capability : in TpPAMCapability 

Specifies which capability of the agent for which attributes are desired. 

attributeNames : in TpStringList 

Specifies the dynamic attributes of interest. Can be an empty array to indicate all dynamic attributes are to be retrieved. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMAttributeList 

Raises 

TpCoirmonExceptions, PPAMUNKNOWNAGENT , PPAMUNKNOWNCAPABILITY, 
P PAM UNKNOWN ATTRIBUTE, P PAM INVALID CREDENTIAL 



8.2.5 Interface Class IpAppPAMPreferenceCheck 

Inherits from: Iplnterface. 

The purpose of this interface is to provide methods to be called by the PAM service to check for access control or to 
compute availability using an implementation provided by an application. Instances of this interface are registered using 
the setPreferenceO method in the availability management interface. 
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«lnterface» 
IpAppPAMPreferenceCheck 



computeAvailability (identity : in TpPAMFQName, pamContext : in TpPAMContext, attributeNames : in 
TpStringList, autin Token : in TpPAMCredential) : TpPAMAvailabilityProfileList 



8.2.5.1 Method computeAvailability() 

Compute the availability for an identity for a given context. The data provided is the same as the data provided for the 
getAvailability call. The application implementing this interface uses the identity presence interface to get the current 
presence data and maintains its own user preferences to compute the availability. 

Returns a value containing a list of attributes as available to the asker in the requested context. If no information is 
available to the asker an empty list is returned. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity for which the availability is being requested. 

pamContext : in TpPAMContext 

Specifies the context for which the availability is requested. 

attributeNames : in TpStringList 

Specifies the attributes of interest. Can be an empty list to indicate all attributes. 

authToken : in TpPAMCredential 
Of the entity who wishes to do this operation. 

Returns 
TpPAMAvailabilityProfileList 

8.3 PAM Event SCF Interface Classes 

This service contains an interface for registering for notifications for events that occur within the PAM service. 

8.3.1 Interface Class IpPAMEventManager 

Inherits from: IpService. 

The purpose of this interface is to supply the various interfaces available in this service to the application and to provide 
the authentication credentials. This interface is the only discoverable interface from the framework. 

All PAM methods use an authentication token as a parameter since the outcome of the operations may depend on 
the entity requesting the operation. To enable this, the getAuthToken() method is used to obtain an implementation 
dependent token. An application that has authenticated itself with the OSA framework, can get an authentication token 
for itself. Alternatively, if the application is requesting PAM operations on behalf of multiple entities, authentication 
tokens may be requested for each such entity after providing any available data about the asker. These tokens can then 
be used repeatedly for operations within a session without further need to identify the asker. 
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«lnterface» 
IpPAMEventManager 



getAuthToken (askerData : in TpAttributeList) : TpPAMCredential 

obtainlnterface (interfaceName : in TpPAMEventlnterfaceName) : IplnterfaceRef 

getAccessControl (identity : in TpPAMFQName, autin Token : in TpPAMCredential) : 
TpPAMAccessControlData 

setAccessControl (identity : in TpPAMFQName, operation : in TpPAMPreferenceOp, newAccessControl : in 
TpPAMAccessControlData, authToken : in TpPAMCredential) : void 

activateService (identity : in TpPAMFQName, authToken : in TpPAMCredential) : void 

deactivateService (identity : in TpPAMFQName, authToken : in TpPAMCredential) : void 

isActiveldentity (identity : in TpPAMFQName, authToken : in TpPAMCredential) : TpBoolean 



8.3.1 .1 Method getAuthToken () 

Get an authentication token for access to the interface methods. 

Returns an implementation-dependent authentication credential that can be verified. 

Parameters 

askerData : in TpAttributeList 

Specifies information about the asker. Can be an empty array. The exact attributes in this list are dependent on the 
application. PAM reserves the attribute "name" with type TpPAMFQName to contain the identity of the asker if known. 

Returns 
TpPAMCredential 

Raises 

TpCoininonExceptions , PPAMINVALIDCREDENTIAL 



8.3.1.2 Method obtain InterfaceO 

Obtain available interfaces from the service. The valid parameters for this method can be obtained from the service 
property P_OBTAINABLE_INTERFACES. 

Returns the requested interface. 

Parameters 

interfaceName : in TpPAMEventlnterfaceName 
Specifies the name of the required interface. 
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Returns 
IpInterfaceRef 

Raises 

TpCommonExceptions , P_PAM_UNAVAILABLE_INTERFACE 



8.3.1.3 Method getAccessControlO 

Get the access control associated with the data belonging to an identity. The data associated with an identity includes 
the static and dynamic attributes of an identity as well as data about agents associated with an identity. 

This method should be used in conjunction with the setAccessControl method. 

Returns the access control if previously specified for the identity. Is null if there is no access control associated. 

Parameters 

identity : in TpPAMFQName 
Specifies the identity of interest. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 

Returns 
TpPAMAccessControlData 

Raises 

TpCommonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 



8.3.1.4 Method setAccessControlO 

Set the access controls for the data associated with the specified identity. If the identity is Null, the access control is set 
for all identities (if authorized to do so). The data associated with an identity includes the static and dynamic attributes 
of an identity as well as data about agents associated with an identity. 

Any existing access control will be modified based on the operation. 

If the new access control is specified as Null for replace operation , an existing access control will be removed. 

Parameters 

identity : in TpPAMFQName 
Specifies the identity of interest. 

operation : in TpPAMPreferenceOp 

Specifies the operation to be performed with the specified preference. 

newAccessControl : in TpPAMAccessControlData 

Specifies the access controls to add. 

authToken : in TpPAMCredential 

Of the entity who wishes to do this operation. 
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Raises 

TpCoirmonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 



8.3.1.5 Method activateServiceO 

Activate the service for the specified identity. If the identity is null, activate the service for ALL identities. The method 
succeeds if the service is already activated for the specified identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. Can be NULL (empty string). 

authToken : in TpPAMCredential 

of the entity who wishes to do this operation. 

Raises 

TpCoirmonExceptions, PPAMUNKNOWNIDENTITY, PPAMINVALIDCREDENTIAL 



8.3.1.6 Method deactivateService() 

Deactivate the service for the specified identity. If the identity is null, deactivate the service for ALL identities. The 
method succeeds if the service is already deactivated for the specified identity. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. Can be NULL (empty string). 

authToken : in TpPAMCredential 

of the entity who wishes to do this operation. 

Raises 

TpCoirmonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.3.1.7 Method isActiveldentityO 

Check if the service is active for the specified identity. Returns true if the service is active for that identity, false 
otherwise. 

Parameters 

identity : in TpPAMFQName 

Specifies the identity of interest. Cannot be NULL (empty string). 

authToken : in TpPAMCredential 
of the entity who wishes to do this operation. 
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Returns 
TpBoolean 

Raises 

TpCommonExceptions, P_PAM_UNKNOWN_IDENTITY, P_PAM_INVALID_CREDENTIAL 



8.3.2 Interface Class IpAppPAMEventHandler 

Inherits from: Iplnterface. 

This is the interface that a client apphcation must implement and register with the Event Service in order to be notified 
of events. 



«lnterface» 
IpAppPAMEventHandler 



eventNotify (eventID : in TpPAMEventID, eventlnfo : in TpPAMNotificationlnfoList) : void 
eventNotifyErr (eventID : in TpPAMEventID, errorlnfo : in TpPAMErrorlnfo) : void 



8.3.2.1 Method eventNotifyQ 

Notify the occurrence of an event. The implementations will not attempt to re-notify on failure. 

Parameters 

eventID : in TpPAMEventID 

Specifies a prior event registration ID. 

eventlnfo : in TpPAMNotificationlnfoList 

Contains the data about the events that occurred. 



8.3.2.2 Method eventNotifyErr() 

Notify an error in the event reporting. The error may concern all assignments, one whole assignment or a part of it. An 
eventNotify is sent after the error condition has passed away unless the event has been subsequently deregistered. Re- 
registration may only be needed in fatal system error cases. Note that in normal operation unavailable or protected 
pieces of presence information are delivered by the normal reporting methods instead of an error method. 

Parameters 

eventID : in TpPAMEventID 

Specifies a prior event registration ID. 
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errorlnfo : in TpPAMErrorlnfo 

Contains the data relating to the error. 



8.3.3 Interface Class IpPAMEventHandler 

Inherits from: Iplnterface. 

The purpose of this interface is to manage the registrations of interest in events and the registration of client interfaces 
for subsequent notification. All notifications in the present document are to be sent after the corresponding event has 
occurred and are asynchronous. An application must first register a notification interface with the service. It can then 
register interest in one or more events for this interface. 

A failure or a reset of a PAM implementation may result in a loss of all prior event and interface registrations. The 
cUent application may need to confirm the continued registration of the notification interface and re-register if 
necessary. 

For security and privacy purposes, a registration for an event is allowed if and only if the supplied credentials during 
registration is sufficient to have allowed access to the information related to the event through one or more of the PAM 
interface methods. 



«lnterface» 
IpPAMEventHandler 



isRegistered (clientlD : in TpPAMCIientID, authloken : in TpPAMCredential) : TpBoolean 

registerApplnterface (applnterface : in IpAppPAMEventHandlerRef, authloken : in TpPAMCredential) : 
TpPAMCIientID 

registerForEvent (clientlD : in TpPAMCIientID, eventList : in TpPAMEventlnfoList, validFor : in TpDuration, 
authToken : in TpPAMCredential) : TpPAMEventID 

deregisterApplnterface (clientlD : in TpPAMCIientID, authToken : in TpPAMCredential) : void 

deregisterFromEvent (eventID : in TpPAMEventID, authToken : in TpPAMCredential) : void 



8.3.3.1 Method isRegisteredQ 

Check if a client application interface is registered. 

Returns True if the registration ID is still valid, False otherwise. 

Parameters 

clientlD : in TpPAMCIientID 

Specifies the registration ID provided at registration. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 
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Returns 
TpBoolean 

Raises 

TpCoinmonExceptions , P_PAM_INVALID_CREDENTIAL 



8.3.3.2 Method registerApplnterface() 

Register a client application's notification interface. 

Returns an ID returned by the service that uniquely identifies this registration. 

Parameters 

applnterface : in IpAppPAMEventHandlerRef 

Specifies the client notification interface. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Returns 
TpPAMClientID 

Raises 

TpCoinmonExceptions , PPAMINVALIDCREDENTIAL 



8.3.3.3 Method registerForEvent() 

Register a client application's interest in one or more events. 

Returns an ID returned by the service that uniquely identifies this registration for the event. 

Parameters 

clientlD : in TpPAMClientID 

Specifies the registration ID provided at registration. 

eventList : in TpPAMEventlnfoList 

Specifies the events of interest. 

validFor : in TpDuration 

Specifies the interval in milliseconds until which the subscription is held and notifications provided. A time interval of 
or negative values indicate a subscription that never expires until explicitly cancelled. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 
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Returns 
TpPAMEventID 

Raises 

TpCommonExceptions, P_PAM_NOT_REGISTERED, P_PAM_INVALID_CREDENTIAL 



8.3.3.4 Method deregisterApplnterface() 

Unregister a client application's notification interface. 

All registrations for events for this client registration are also removed. 

Parameters 

clientlD : in TpPAMClientID 

Specifies the registration ID provided at registration. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMNOTREGISTERED, PPAMINVALIDCREDENTIAL 



8.3.3.5 Method deregisterFromEvent() 

Unregister a client application's interest in an event. 

Parameters 

event ID : in TpPAMEventID 

Specifies a prior event registration ID. 

authToken : in TpPAMCredential 
Credential of the entity who wishes to do this operation. 

Raises 

TpCommonExceptions, PPAMNOTREGISTERED, PPAMINVALIDCREDENTIAL 



9 State Transition Diagrams 

There are no State Transition Diagrams for the Presence and Availability Management SCFs. 
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1 PAM Service Properties 

The following table lists properties relevant to all the PAM SCFs. 



Property 


Type 


Description 


P_OBTAINABLE_INTERFACES 


STRING_SET 


The interfaces obtainable from the service. 


P_SUPPORTED_ATTRIBUTE_TAGS 


STRING_SET 


Lists the supported attribute tags defined by 
TpAttributeTaglnfo. 


P SUPPORTED SIMPLE ATTRIBUTE 
_TYPES 


STRING_SET 


Lists the supported attribute types defined by 
TpSimpleAttributeTypelnfo. 


P SUPPORTED STRUCTURED ATTRI 
BUTE_TYPES 


STRING_SET 


Lists the supported attribute types defined by 
TpStructuredAttributeType, e.g. P_org/csapi/TpAddress. 


P_SUPPORTED_XML 


STRING_SET 


Lists the supported versions of XML specifications such as 

XML schema specifications (e.g. through URLs), XML 

versions (e.g. version LO) or XPath (e.g. version LO). 



Implementations of the PAM APIs shall have the Service Properties set to the indicated values at a minimum: 



P_SUP PORTED_ATTRI BUTE_TAGS 
P SIMPLE TYPE 



{ 



P_SUPPORTED_SIMPLE_ATTRIBUTE_TYPES 
P_STRING, 
P_FLOAT , 
P INT32 



10.1 PAIVI Access Service 



Implementations of the PAM Access APIs for 3GPPshall have the Service Properties set to the indicated values: 



P_OBTAINABLE_INTERFACES = { 
P_PAM_IDENTITY_PRESENCE , 
P PAM AVAILABILITY 



10.2 PAM Event Service 

PAM Event service has the following property in addition to the above. 



Property 


Type 


Description 


P_EVENT_TYPES 


INTEGER_SET 


The pre-defined event types that can be registered for 



11 



PAIVI Data Definitions 



All data types referenced in this document but not defined in this clause are common data definitions which may be 
found in 3GPP TS 29.198-2. 

11.1 Entity Address Definitions 
11.1.1 TpPAMFQName 

This is the same as TpURN and is used to name entities in PAM Access service. 
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11.1.2 TpPAMFQNameList 



This is a Numbered List of Data Elements of type TpPAMFQName. 



1 1 .2 Attribute Data Definitions 



11.2.1 TpPAIVIAttribute 



This is a Sequence of Data Elements containing the attribute name, expiration time and value. This is derived 
from the common attribute type TpAttribute to add the expiration value for dynamic attributes. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


AttributeName 


TpString 


The name of the attribute. 


AttributeValue 


TpAttributeValue 


The typed value(s) for the attribute. 


Expiresin 


TpPAMTimelnterval 


The interval in milli.seconds in which the attribute values are 

vaUd. A time interval of PAM_MAX_LONGINT indicates 

static attribute values that never expire. A time interval of or 

negative values indicate an expired value and the time for 

which it has expired. 



1 1 .2.2 TpPAIVIAttrlbuteLlst 



This is a Numbered List of Data Elements of type TpP AM Attribute. 



1 1 .2.3 TpPAIVIAttributeDef 



This is a Sequence of Data Elements containing the definition of an attribute. This definition constitutes the 
"schema" for an attribute and contains fields to define the type and behavior of a dynamic attribute. Each definition 
using these fields results in a TpPAMAttribute with the corresponding name and type and dynamic behavior as defined 
by the remaining fields. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Name 


TpString 


Name of attribute 


Type 


TpString 


Type of attribute. Valid values for Type must include at least 
TpString, Tplnt32 and TpHoat 


IsStatic 


TpBoolean 


True indicates that the attributes is always static and its values 

never expire. False indicates that the attribute can be dynamic 

and may contain values that expire. 


IsRevertOnExpiration 


TpBoolean 


True indicates that the attribute reverts to the default value on 

expiration. False indicates that the attribute will not revert to the 

default value. 


Def aultValues 


TpAny 


An attribute is always initialized with this value. If the 

IsRevertOnExpiration attribute is set to true, a dynamic attribute 

that has expired while stored in a PAM implementation is reset 

to this value with the expiresin interval set to 

PAM_MAX_LONGINT. The default attribute value is 

inteipreted based on the value of the attribute Type. 



1 1 .2.4 TpPAIVIAttrlbuteDefLlst 

This is a Numbered List of Data Elements of type TpPAMAttributeDef. 
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1 1 .3 Presence Data Definitions 
11.3.1 TpPAIVICapability 

This defines the extensible communication capabiHties. This data type is identical to a TpString, and is defined as a 
string of characters that specify the communication capabilities. The following strings are pre-defined. 



Character String Value 


Description 


P_PAM_VOICE 


Capability for voice calls 


P_PAM_SMS 


Capability for SMS 


P_PAM_IM 


Capability for Instant Messaging 


P_PAM_MMS 


Capability for Multi-media messaging 



11.3 



tf 



This is 



Numbered List of Data Elements of type TpPAMCapability. 

1 1 .3.3 TpPAIVIPresenceData 

This is a Sequence of Data Elements for a specific identity type Presentity pre-defined in PAM. Since 
multiple presence data records can be associated with an identity, each distinct record is uniquely named. 



Sequence Element Name 


Sequence Element Type 


Notes 


Name 


TpString 


Name of presence data 


PresenceAt tributes 


TpPAMAttributeList 


Presence Attributes 



1 1 .3.4 TpPAIVIPresenceDataLlst 

This is a Numbered List of Data Elements of type TpPAMPresenceData. 

1 1 .4 Pre-defined Presence type 
11.4.1 Presentity 

An identity type Presentity is pre-defined for all identities associated with the attribute PresenceProfile defined as: 



Attribute Definition Field 


Value 


Name 


PresenceProfile 


Type 


TpPAMPresenceData 


IsStatic 


False 


IsRevertOnExpiration 


False 


DefaultValues 


Null 
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1 1 .5 Availability Data Definitions 
11.5.1 TpPAMAvailabilityProf ile 

This is a Sequence of Data Elements containing the list of attribute values as determined by the definition of 
the context for which the availability is provided. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


PrivacyCode 


TpPAMPrivacyCode 


Contains the privacy codes 


AvailabilityData 


TpPAMPresenceData 


Contains a list of presence attributes 



1 1 .5.2 TpPAMAvailabilityProfileList 

This is a Numbered List of Data Elements of type TpPAMAvailabilityProfile. 

1 1 .5.3 TpPAMPrivacyCode 

This data type is identical to a TpString, and is defined as a string of characters that specify the privacy code for 
availability profiles. These codes are just indications of the privacy expected by the service and not are meant to be 
enforced by the service. Other Network operator specific codes may also be used, but should be preceded by the string 
" S_". The following values are defined. 



Character String Value 


Description 


PAM_CP_ASKER_ONLY 


The profile is available to the asker only and should not be further transmitted 


PAM_C P_AUTHOR I Z ED 


The profile can be provided by the asker to authorized entities 


PAM_CP_UNLIMITED 


The profile can be distributed without limits 



1 1 .6 Availability Context Data Definitions 

Availability is always queried for in a specific context on behalf of an asker. There is one context for communication 
pre-defined in this version of the specification. 

11.6.1 TpPAMContext 

This is a Sequence of Data Elements containing the data which defines the context in which an availability is 
queried and information about the asker that is requesting the data. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


ContextData 


TpPAMContextData 


Contains the context name and the list of attributes that define the 

context. The attributes to be included for a given context are 

specified by the definition of the context. 


AskerData 


TpAttributeList 


Contains information about the asker of availabihty. The exact 

attributes in this list are dependent on the apphcation. PAM 

reserves the attribute "name" with type TpPAMFQName to 

contain the identity of the asker if known. 
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1 1 .6.2 TpPAMContextName 

This specifies the availability contexts. 



Name 


Value 


Description 


PAM_CONTEXT_ANY 





Denotes any known context 


PAM_CONTEXT_COMMUNI CATION 


1 


Denotes a communication context 



1 1 .6.3 TpPAMContextData 



This is a tagged choice of data elements that specifies the optional data that may be required to define a 
particular context. 





Tag Element Type 






TpPAMContextName 






Tag Element Value 


Choice Element Type 


Choice Element Name 


PAM_CONTEXT_ANY 


None 


Undefined 


PAM_CONTEXT_COMMUNICATION 


TpPAMCommunicationContext 


CommunicationContext 



1 1 .6.4 TpPAMCommunicationContext 



This is a Sequence of Data Elements containing the list of attribute values for defining a communication 
context. 



Sequence Element Name 


Sequence Element Type 


Notes 


CommunicationCapability 


TpPAMCapability 


Specifies the communication type for which the availability 
is requested 



1 1 .6.5 TpPAMContextList 

This is a Numbered List of Data Elements of type TpPAMContext. 

1 1 .7 Credential data definitions 
11.7.1 TpPAIVICredential 

This is the same as TpOctetSet. This data is opaque to the application and is implementation dependent. As this data is 
valid only in the context of a single session with the service and hence cannot be used across multiple services, there are 
no inter-operability issues here. The application simply uses the credential returned from the getAuthToken() method in 
all other methods that require the credentials. 

1 1 .8 Availability and Access Control Preference Data Definitions 

PAM allows several types of preferences to be specified. It includes an access control list specifying who is allowed to 
check for presence or subscribe to presence data for each identity. It also includes an interface for an application to 
register an interface to do access control checks and availability computations outside of the presence service. 

11.8.1 IpAppPAMPreferenceCheckRef 

Defines a Reference to type IpAppPAMPreferenceCheck. 
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1 1 .8.2 TpPAMAccessControlData 

This is a Sequence of Data Elements for access control data. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Def aultPolicy 


TpPAMACLDefault 


Specifies whether the default poUcy is to allow or deny access 
for names not mentioned in the list 


AllowList 


TpPAMFQNameLi£5t 


Specifies a list of identities to be allowed access 


DenyList 


TpPAMFQNameLi£5t 


Specifies a list of identities to be denied access 



11.8.3 TpPAMACLDefault 

Defines the two possible default policies for access control. 



Name 


Value 


Description 


PAM_ACCESS_ALLOW 





Allow access by default 


PAM_ACCESS_DENY 


1 


Deny access by default 



1 1 .8.4 TpPAMPreferenceOp 



This data type is identical to a TpString, and is defined as a string of characters that specify the operations to be 
performed with a preference. The following values are defined. 



Character String Value 


Description 


PAM_ACCESS_ADD 


Add the specified preference to the current preferences 


PAM_ACCESS_DELETE 


Delete the specified preference from the current preferences 


PAM_ACCESS_REPLACE 


Replace the current preferences with the specified preference 



11.8 



tf 



This specifies the names of privacy and access control mechanisms supported by the service. 



Name 


Value 


Description 


PAM_ACCESS_LIST 





The control data contains additions or modifications to access 
control list of who is authorized to access the presence 
information or subscribe to it. 


PAM_EXTERNAL_CONTROL 


1 


The access control and availability computations are done 
external to the presence service 



1 1 .8.6 TpPAMPreferenceData 



This is a tagged choice of data elements that specifies the preference data. The data depends on the type 
of preference being specified. 





Tag Element Type 






TpPAMPref erenceType 






Tag Element Value 


Choice Element Type 


Choice Element Name 


PAM_EXTERNAL_CONTROL 


IpAppPAMPref erenceCheckRef 


Ext ernalControl Inter face 
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1 1 .9 Time data definitions 
11 .9.1 TpPAIVITI me Interval 

This is identical to Tplnt64. 

11.10 Pre-defined Entity Types and Attributes 

This version of the specification pre-defines one identity type called "Presentity". The following constant can be used to 
refer to this Identity Type. All identities in the PAM service are associated with this identity type. For example, the 
identityType parameter in IpIdentityPresence and IpEventHandler methods take this as the value. This is also used in 
the event registration data structure (e.g., TpPAMAVCEventData) in the IdentityType field. 



Character String Value 


Description 


P PAM PRESENTITY TYPE 


The pre-defined identity type called Presentity. 



Every identity type in PAM can be defined with a set of attributes that are associated with all identities of that type. The 
following dynamic attributes are pre-defined as attributes of type TpPAMAttribute for the "Presentity" identity type and 
shall be supported as attributes of all identities in implementations of this service. These attributes are defined using 
TpPAMAttributeDef fields as follows. 



AttributeName 


AttributeType 


IsStatic 


IsRevertOn 
Expiration 


DefaultValue 


Description 


P_SUBSCRIBER_STATUS 


P_STRING 


False 


False 


None 


Specifies the status of the 
subscriber 


P_NETWORK_STATUS 


P_STRING 


False 


False 


None 


Specifies the status of the 
network 


P COMMUNICATION MEAN 
S 


P_org/csapi/pa 

m/TpPAMCap 

ability 


False 


False 


None 


Specifies the means of 

communication. The type is 

TpPAMCapability 


P_CONTACT_ADDRESS 


P_org/csapi/Tp 
Address 


False 


False 


None 


Address for communication 


P SUBSCRIBER PROVIDE 
D_LOCATION 


P_STRING 


False 


False 


None 


Location nformation provided 
by subscriber. Is optional. 


P NETWORK PROVIDED L 
OCATION 


P_STRING 


False 


False 


None 


Location information provided 
by subscriber. Is optional. 


P_PRIORITY 


P_INT32 


False 


False 


None 


Priority for communication 


P_OTHER_INFO 


P_STRING 


False 


False 


None 


Additional information 



11.11 Interface name definitions 

This section defines the names to be used for obtaining interfaces from the corresponding service interfaces in each 
PAM SCF. 

11.11.1 TpPAMProvisioninglnterfaceName 

This data type is identical to a TpString, and is defined as a string of characters that identify the names of the PAM 
Provisioning interfaces that are to be supported by the OSA API. 



Character String Value 


Description 


P PAM IDENTITY MANAGEMENT 


The name for the PAM Identity Management interface. 


P PAM AGENT MANAGEMENT 


The name for the PAM Agent Management interface 


P PAM AGENT ASSIGNMENT 


The name for the PAM Agent Assignment interface 


P PAM IDENTITY TYPE MANAGEMENT 


The name for the PAM Identity Type Management interface 


P PAM AGENT TYPE MANAGEMENT 


The name for the PAM Agent Type Management interface 


P PAM CAPABILITY TYPE MANAGEMENT 


The name for the PAM Capability Type Management interface 
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11 .11 .2 TpPAMPresenceAvailabilitylnterfaceName 

This data type is identical to a TpString, and is defined as a string of characters that identify the names of the PAM 
Access interfaces that are to be supported by the OSA API. 



Character String Value 


Description 


P PAM IDENTITY PRESENCE 


The name for the PAM Identity Presence interface. 


P PAM AGENT PRESENCE 


The name for the PAM Agent Presence interface 


P PAM AVAILABILITY 


The name for the PAM Availability interface 



11.11.3 TpPAMEventlnterfaceName 

This data type is identical to a TpString, and is defined as a string of characters that identify the names of the PAM 
Event management interfaces that are to be supported by the OSA API. 



Character String Value 


Description 


P PAM EVENT HANDLER 


The name for the Event Handler interface. 



11.12 Event data definitions 

There are two sets of data structures used for events. One set is used by applications to provide information when 
registering for an event and the second set is used to supply information to the applications in the notifications when the 
events occur. 

11.12.1 IpAppPAIVIEventHandlerRef 

Defines a Reference to type IpAppPAMEventHandler. 

11.12.2 TpPAIVICIIentlD 

This is the same is Tplnt32 and is used to identify, uniquely within an implementation, registration of an application 
interface for notification of events. 



11.12.3 TpPAIVIEventID 



This is the same as TpAssignmentID and is used to identify, uniquely within an implementation, a registration for a 
specific event. 
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11.12.4 TpPAMEventName 

This data type identifies the values that specify the event names. 



Name 


Value 


Description 


PAM_CE_IDENTITY_PRESENCE_SET 





Notify if the value of presence attributes of an identity is 
explicitly set 


PAM_CE_AVAI LAB I L I TY_CHANGED 


1 


Notify if the availability of an identity changes 


PAM_CE_WATCHERS_CHANGED 


2 


Notify if the current set of watchers change 


PAM_CE_IDENTITY_CREATED 


3 


Notify if a new identity has been created 


PAM_CE_I DENTI TY_DELETED 


4 


Notify if an identity has been deleted 


PAM_CE_GROUP_MEMBERSHI P_CHANGED 


5 


Notify if the membership of a group changes 


PAM_CE_AGENT_CREATED 


6 


Notify if a new agent has been created 


PAM_CE_AGENT_DELETED 


7 


Notify if an agent has been deleted 


PAM_CE_AGENT_AS S I GNED 


8 


Notify if an agent is assigned to an identity 


PAM_CE_AGENT_UNAS S I GNED 


9 


Notify if an agent has been unassigned from an identity 


PAM_CE_CAPAB I L I TY_CHANGED 


10 


Notify if the capability of an identity changes 


PAM_CE_AGENT_CAPABILITY_PRESENCE_SET 


11 


Notify if the value of presence attributes of an agent is 
explicitly set 


PAM_CE_AGENT_PRESENCE_SET 


12 


Notify if the value of presence attributes of an agent is 
explicitly set 



11.12.5 TpPAMEventNameList 

This is a Numbered List of Data Elements of type TpPAMEventName. 

Each event is defined by the data that appHcations must provide during registration using TpPAMEventlnfo and data 
that is provided to the apphcation during notification of such events using TpPAMNotificationlnfo. 



11.12.6 TpPAMEventlnfo 



This is a tagged choice of data elements that specifies the event data provided by appHcations while 
registering. 





Tag Element Type 






TpPAMEventName 






Tag Element Value 


Choice Element Type 


Choice Element Name 


PAM_CE_IDENTITY_PRESENCE_SET 


TpPAMIPSEventData 


IdentityPresenceSet 


PAM_CE_AVAI LAB I L I TY_CHANGED 


TpPAMAVCEventData 


AvailabilityChanged 


PAM_CE_WATCHERS_CHANGED 


TpPAMWCEventData 


Wat Cher sChanged 


PAM_CE_IDENTITY_CREATED 


TpPAMICEventData 


IdentityCreated 


PAM_CE_IDENTITY_DELETED 


TpPAMIDEventData 


IdentityDeleted 


PAM_CE_GROUP_MEMBERSHI P_CHANGED 


TpPAMGMCEventData 


GroupMembershipChanged 


PAM_CE_AGENT_CREATED 


TpPAMACEventData 


AgentCreated 


PAM_CE_AGENT_DELETED 


TpPAMADEventData 


AgentDeleted 


PAM_CE_AGENT_AS S I GNED 


TpPAMAAEventData 


Agent As s igned 


PAM_CE_AGENT_UNAS S I GNED 


TpPAMAUEventData 


AgentUnas signed 


PAM_CE_CAPAB I L I TY_CHANGED 


TpPAMCCEventData 


CapabilityChanged 


PAM_CE_AGENT_CAPABILITY_PRESENCE_SET 


TpPAMACPSEventData 


Agent CapabilityPresenceSet 


PAM_CE_AGENT_PRESENCE_SET 


TpPAMAPSEventData 


Agent PresenceSet 
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11.12.7 TpPAMEventlnfoList 

This is a Numbered List of Data Elements of type TpPAMEventlnfo. 

11.12.8 TpPAMNotificationlnfo 

This is a tagged choice of data elements that specifies the notification data provided to the applications 
for each event. 





Tag Element Type 






TpPAMEventName 






Tag Element Value 


Choice Element Type 


Choice Element Name 


PAM_CE_IDENTITY_PRESENCE_SET 


TpPAMIPSNotif icationData 


IdentityPresenceSetNotify 


PAM_CE_AVAI LAB I L I TY_CHANGED 


TpPAMAVCNot i f i cat ionData 


AvailabilityChangedNotify 


PAM_CE_WATCHERS_CHANGED 


TpPAMWCNotif icationData 


WatchersChangedNotify 


PAM_CE_IDENTITY_CREATED 


TpPAMICNot if icationData 


IdentityCreatedNotify 


PAM_CE_IDENTITY_DELETED 


TpPAMIDNot if icationData 


IdentityDeletedNotify 


PAM_CE_GROUP_MEMBERSHI P_CHANGED 


TpPAMGMCNotif icationData 


GroupMember shipChangedNot i f y 


PAM_CE_AGENT_CREATED 


TpPAMACNotif icationData 


AgentCreatedNotify 


PAM_CE_AGENT_DELETED 


TpPAMADNot if icationData 


AgentDeletedNotify 


PAM_CE_AGENT_AS S I GNED 


TpPAMAANot if icationData 


Agent As s ignedNot i f y 


PAM_CE_AGENT_UNAS S I GNED 


TpPAMAUNot if icationData 


AgentUnas s ignedNot i f y 


PAM_CE_CAPAB I L I TY_CHANGED 


TpPAMCCNot if icationData 


Capabi 1 i tyChangedNot i f y 


PAM_CE_AGENT_CAPAB I L I TY_PRES ENC 
E_SET 


TpPAMACPSNot if icationData 


AgentCapabilityPresenceSetNotify 


PAM_CE_AGENT_PRESENCE_SET 


TpPAMAPSNot i f i cat ionData 


AgentPresenceSetNotify 



11.12.9 TpPAMNotificationlnfoList 

This is a Numbered List of Data Elements of type TpPAMNotificationlnfo. 

1 1 .1 2.1 PAM_CEJDENTITY_CREATED 

Notify if a new identity has been created. Notifications for creation of muhiple identities are bunched into a single 
notification whenever possible. A notification of this event is NOT sent for new association of types with an existing 
identity. 

11.12.10.1 TpPAMICEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to identity creations. The event 
is registered for changes in any agents of the named type. If no identity types are named, then the event is registered for 
all identity types. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


IdentityType 


TpStringList 


Specifies the type of the identities for which this notification 

is requested. Can be an empty array if notification required 

for identities of any type. 
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1 1 .1 2.1 0.2 TpPAMICNotificationData 



This is a Sequence of Data Elements to specify the data that is provided in the notifications for identity 
creation events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identities 


TpPAMFQNameList 


Contains the names of the identities that have been created. 



11 .12.11 PAM_CEJDENTITY_DELETED 

Notify if an identity has been deleted. Notifications for deletion of multiple identities are bunched into a single 
notification whenever possible. A notification of this event is NOT sent for removing association of types with an 
existing identity. 

11.12.11.1 TpPAMIDEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to identity deletions. The event 
is registered for changes in any of the named identities. If no identities are named, then the event is registered for all 
agents. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


IdentityName 


TpPAMFQNameList 


Specifies the name of the identity whose deletion is to be 
notified. Can be an empty array 


IdentityType 


TpStringList 


Specifies the type of the identity for which this notification is 

requested if identityName is an empty array. Can be an empty 

array if notification required for identities of any type 



1 1 .1 2.1 1 .2 TpPAMIDNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for identity 
deletion events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identities 


TpPAMFQNameList 


Contains the names of the identities that have been deleted. 



11.12.12 PAM_CE_GROUP_MEMBERSHIP_CHANGED 

Notify if the membership of a group changes. Notifications for changes to multiple groups are bunched into a single 
notification whenever possible. 
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11.12.12.1 TpPAMGMCEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to group membership changes. 
The event is registered for changes in any of the named groups. If no groups are named, then the event is registered for 
all groups. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


GroupName 


TpPAMFQNameList 


Specifies the name of the group for which the change is to be 

notified. Can be an empty array if notifications are required 

for any group. 


GroupType 


TpStringList 


Specifies the type of the group for which this notification is 

requested if the groupName is specified as an empty array. 

Can be an empty array if notification required for groups of 

any type. 



1 1 .1 2.1 2.2 TpPAMGMCNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for group 
membership changes. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Groups 


TpPAMFQNameList 


Contains the names of the groups that have been changed. 



11.12.13 PAM_CE_AGENT_CREATED 

Notify if a new agent has been created. Notifications for creation of multiple agents are bunched into a single 
notification whenever possible. The notification for this event is NOT sent for new associations of types with agents. 

11.12.13.1 TpPAMACEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to agent creations. The event is 
registered for changes in any agents of the named type. If no agent types are named, then the event is registered for all 
agent types. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


AgentType 


TpStringList 


Specifies the type of the agents for which this notification is 

requested. Can be an empty array if notification required for 

agents of any type 



1 1 .1 2.1 3.2 TpPAMACNotificationData 



This is a Sequence of Data Elements to specify the data that is provided in the notifications for agent creation 
events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Agents 


TpPAMFQNameList 


Contains the names of the agents that have been created. 



11.12.14 PAM_CE_AGENT_DELETED 

Notify if an agent has been deleted. Notifications for deletion of multiple agents are bunched into a single notification 
whenever possible. This event notification is NOT sent for disassociating a type from an agent. 
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11.12.14.1 TpPAMADEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to agent deletions. The event is 
registered for changes in any of the named agents. If no agents are named, then the event is registered for all agents. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


AgentName 


TpPAMFQNameList 


Specifies the name of the agent whose deletion is to be 
notified. Can be an empty array 


AgentType 


TpStringList 


Specifies the type of the agent for which this notification is 

requested if agentName is an empty array. Can be an empty 

array if notification required for agents of any type 



11.12.14.2 TpPAMADNotificationData 



This is a Sequence of Data Elements to specify the data that is provided in the notifications for agent deletion 
events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Agents 


TpPAMFQNameList 


Contains the names of the agents that have been deleted. 



11.12.15 PAM_CE_AGENT_ASSIGNED 

Notify if an agent is assigned to an identity. 

11.12.15.1 TpPAMAAEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to agent assignments from an 
identity. The event is registered for changes in any of the named agents. If no agents are named, then the event is 
registered for any agent. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


IdentityName 


TpPAMFQNameList 


Specifies the name of the identity for which the assignment is 

to be notified. Can be an empty array if notification is 

required for any identity instance. 


IdentityType 


TpStringList 


Specifies the type of the identity for which this notification is 

requested if the IdentityName is specified as an empty array. 

Can be an empty array if notification required for identities of 

any type. 


AgentName 


TpPAMFQNameList 


Specifies the name of the agent whose assignment is to be 
notified. Can be an empty array 


AgentType 


TpStringList 


Specifies the type of the agent for which this notification is 

requested if agentName is an empty array. Can be an empty 

array if notification required for agents of any type 



1 1 .1 2.1 5.2 TpPAMAANotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for agent 
assignment events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identity 


TpPAMFQName 


Contains the name of the identity to whom an agent has been 
assigned. 


Agent 


TpPAMFQName 


Contains the name of the agent that has been assigned. 
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11.12.16 PAM_CE_AGENT_UNASSIGNED 

Notify if an agent has been unassigned from an identity. 

11.12.16.1 TpPAMAUEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to agent unassignments from an 
identity. The event is registered for changes in any of the named agents. If no agents are named, then the event is 
registered for all assigned agents. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identity-Name 


TpPAMFQNameList 


Specifies the name of the identity for which the unassignment 

is to be notified. Can be an empty array if notification is 

required for any identity instance. 


IdentityType 


TpStringList 


Specifies the type of the identity for which this notification is 

requested if the identityName is specified as an empty array. 

Can be an empty array if notification required for identities of 

any type. 


AgentName 


TpPAMFQNameList 


Specifies the name of the agent whose unassignment is to be 
notified. Can be an empty array. 


AgentType 


TpStringList 


Specifies the type of the agent for which this notification is 

requested if agentName is an empty array. Can be an empty 

array if notification required for agents of any type. 



1 1 .1 2.1 6.2 TpPAMAUNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for agent 
unassignment events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identity 


TpPAMFQName 


Contains the name of the identity from whom an agent has 
been unassigned. 


Agent 


TpPAMFQName 


Contains the name of the agent that has been unassigned. 



11.12.17 PAM_CE_CAPABILITY_CHANGED 

Notify if the capability of an identity changes. 

11.12.17.1 TpPAMCCEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to identity capability changed 
events. The event is registered for changes in any of the named capabilities. If no capabilities are named, then the event 
is registered for all capabilities. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


IdentityName 


TpPAMFQNameList 


Specifies the name of the identity for which the capability 

change is to be notified. Can be an empty array if notification 

is required for any identity instance. 


IdentityType 


TpStringList 


Specifies the type of the identity for which this notification is 

requested if the identityName is specified as an empty array. 

Can be an empty array if notification required for identities of 

any type. 


Capabilities 


TpPAMCapabilityList 


Specifies the capabilities of interest. Can be an empty array if 
notifications are required for any capability. 
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1 1 .1 2.1 7.2 TpPAMCCNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for capability 
change events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identity 


TpPAMFQName 


Contains the name of the identity whose capability has 
changed. 


Capabilities 


TpPAMCapabilityList 


Contains the capabilities that have changed (i.e., added or 
removed). 



11.12.18 PAM_CE_AGENT_CAPABILITY_PRESENCE_SET 

Notify if the value of capability presence attributes of an agent is set. Expiration of the dynamic attributes does not 
trigger this notification. 

11.12.18.1 TpPAMACPSEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to agent capability presence set 
events. The event is registered for changes in any of the named attributes. If no attributes are named, then the event is 
registered for all attributes in the presence information. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


AgentName 


TpPAMFQNameList 


Specifies the name of the agent for which the capability 

presence change is to be notified. Can be an empty array if 

notification is required for any agent instance. 


AgentType 


TpStringList 


Specifies the type of the agent for which this notification is 

requested if the agentName is specified as an empty array. 

Can be an empty array if notification required for agents of 

any type. 


Capabilities 


TpPAMCapabilityList 


Specifies the capabilities of interest. Can be an empty array if 
notifications are required for any capability. 


AttributeNames 


TpStringList 


Specifies attributes of interest. Can be an empty array 


Report ingPeriod 


Tp PAMT i me I nt e r va 1 


Specifies the interval for periodic reporting (regardless of 

change). If -1, the event notification happens only on a 

change. If 0, there is a single immediate notification. 



1 1 .1 2.1 8.2 TpPAMACPSNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for capability 
presence set events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Agent 


TpPAMFQName 


Contains the name of the agent whose capability presence has 
changed 


Capability 


TpPAMCapability 


Specifies the capability for which the presence has changed. 


AttributeNames 


TpStringList 


Contains the attribute names that have changed in value 



11.12.19 PAM_CE_AGENT_PRESENCE_SET 

Notify if the value of presence attributes of an agent is set. Expiration of the dynamic attributes does not trigger this 
notification. 
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11.12.19.1 TpPAMAPSEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to agent presence set events. 
The event is registered for changes in any of the named attributes. If no attributes are named, then the event is registered 
for all attributes in the presence information. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


AgentName 


TpPAMFQNameList 


Specifies tlie name of the agent for wliicli tlie a.ssignment is to 

be notified. Can be an empty array if notification is required 

for any agent instance. 


AgentType 


TpStringList 


specifies the type of the agent for which this notification is 

requested if the agentName is specified as an empty array. 

Can be an empty array if notification required for agents of 

any type. 


AttributeNames 


TpStringList 


Specifies attributes of interest. Can be an empty an"ay. 


Report ingPeriod 


TpPAMTimelnterval 


Specifies the interval for periodic reporting (regardless of 

change). If -1, the event notification happens only on a 

change. If 0, there is a single immediate notification. 



1 1 .1 2.1 9.2 TpPAMAPSNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for agent 
presence set events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Agent 


TpPAMFQName 


Contains the name of the agent whose capability has changed 


AttributeNames 


TpStringList 


Contains the attribute names that have changed in value 



11.12.20 PAM_CEJDENTITY_PRESENCE_SET 

Notify if the value of presence attributes of an identity is set. Expiration of the dynamic attributes does not trigger this 
notification. 

11.12.20.1 TpPAMIPSEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to identity presence set events. 
The event is registered for changes in any of the named attributes. If no attributes are named, then the event is registered 
for all attributes in the presence information. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identity-Name 


TpPAMFQNameList 


Specifies the name of the identity for which the assignment is 

to be notified. Can be an empty array if notification is 

required for any identity instance. 


IdentityType 


TpStringList 


specifies the type of the identity for which this notification is 

requested if the identityName is specified as an empty array. 

Can be an empty array if notification required for identities of 

any type. 


AttributeNames 


TpStringList 


Specifies attributes of interest. Can be an empty an"ay. 


Report ingPeriod 


TpPAMTimelnterval 


Specifies the interval for periodic reporting (regardless of 

change). If -1, the event notification happens only on a 

change. If 0, there is a single immediate notification even if 

there is no change. For all other values, there is a periodic 

notification at the specified time interval regardless of 

change. 
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1 1 .1 2.20.2 TpPAMIPSNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for identity 
presence set events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identity- 


TpPAMFQName 


Contains the name of the identity whose capability has 
changed 


Attributes 


TpPAMPresenceDataList 


Contains the attributes that have changed in value 



11.12.21 PAM_CE_AVAILABILITY_CHANGED 

Notify if the availabihty of an identity changes. The event is registered for changes in any of the named attributes. If no 
attributes are named, then the event is registered for all attributes in the presence information. 

11.12.21.1 TpPAMAVCEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to availability changed events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identity-Name 


TpPAMFQNameList 


Specifies the name of the identity for which the assignment is 

to be notified. Can be an empty aiTay if notification is 

required for any identity instance. 


IdentityType 


TpStringList 


specifies the type of the identity for which this notification is 

requested if the identityName is specified as an empty array. 

Can be an empty array if notification required for identities of 

any type. 


PAMContext 


TpPAMContextList 


Specifies the context in which the availability is to be 
monitored. Cannot be an empty array 


AttributeNames 


TpStringList 


Specifies attributes of interest. Can be an empty array 


Report ingPeriod 


TpPAMTime Interval 


Specifies the interval for periodic reporting (regardless of 

change). If -1, the event notification happens only on a 

change. If 0, there is a single immediate notification even if 

there is no change. For all other values, there is a periodic 

notification at the specified time interval regardless of 

change. 



1 1 .1 2.21 .2 TpPAMAVCNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for availability 
changed events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Identity 


TpPAMFQName 


Contains the name of the identity whose capability has 
changed 


Availability 


TpPAMAvailabilityProf 
ileList 


Contains the availabihty information that has changed 



11.12.22 PAM_CE_WATCHERS_CHANGED 

Notify if list of watchers for any event changed. 
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1 1 . 1 2.22. 1 TpPAMWCEventData 

This is a Sequence of Data Elements to specify the input data for subscribing to watchers changed events. 



Sequence Element Name 


Sequence Element 
Type 


Notes 


Events 


TpPAMEventNameLi s t 


Specifies the list of events for which the watchers are to be 

monitored. Can be an empty array if notification is required 

for watchers to any event 


IdentityName 


TpPAMFQNameList 


Specifies the name of an identity for whom the change in 

watchers is to be notified. Can be an empty array if 

notification is required for any identity instance. 


IdentityType 


TpStringList 


specifies the type of the identity for which this notification is 

requested if the identityName is specified as an empty array. 

Can be an empty array if notification required for identities of 

any type. 


Report ingPeriod 


TpPAMTime Interval 


Specifies the interval for periodic reporting (regardless of 

change). If -1, the event notification happens only on a 

change. If 0, there is a single immediate notification even if 

there is no change. For all other values, there is a periodic 

notification at the specified time interval regardless of 

change. 



1 1 .1 2.22.2 TpPAMWCNotificationData 

This is a Sequence of Data Elements to specify the data that is provided in the notifications for watchers 
changed events. 



Sequence Element Name 


Sequence Element Type 


Notes 


Event 


TpPAMEventName 


Contains the name of the event for which the watchers 
changed 


ChangeType 


TpPAMwatcherChangeType 


Specifies whether the hsted watchers were added or 
deleted 


Identity 


TpPAMFQName 


Contains the name of the identity whose capability has 
changed 


Watchers 


TpPAMFQNameList 


Contains the list of watchers involved in the change 



1 1 . 1 2.22.3 TpPAMwatcherChangeType 

This specifies the values representing the type of change that occurred to the Hst of watchers. 



Name 


Value 


Description 


PAM_WATCHERS_PERIODIC 





Periodic reporting, not necessarily a change. 


PAM_WATCHERS_ADDED 


1 


Watchers added to the list 


PAM_WATCHERS_DELETED 


2 


Watchers deleted from the list 



11.13 Error Types 
11.13.1 TpPAMErrorCause 

This defines the types of errors reported by PAM. 
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Name 


Value 


Description 


P_PAM_CAUS E_UNDE FINED 





Undefined. 


P_PAM_CAUSE_INVALID_ADDRESS 


1 


The request cannot be handled because the address specified is not valid. 


P_PAM_CAUSE_SYSTEM_FAILURE 


2 


System failure. 

The request cannot be handled because of a general problem in the service 

or in the underlying network. 


P_PAM_CAUSE_INFO_UNAVAILABLE 


3 


The information is currently not available. 


P_PAM_CAUSE_EVENT_REGISTRATION_CANCELLED 


4 


The registration for the event has been cancelled by the service. 



11.13.2 TpPAMErrorlnfo 



This is a Sequence of Data Elements to specify the error notification data. 



Sequence Element Name 


Sequence Element 
Type 


Description 


Cause 


TpPAMErrorCause 


Contains information about the reason for the error 


ErrorData 


TpPAMNotificationlnfo 


Contains information relevant to each error such as the 

identity for which the eiTor exists and/or the attributes for 

which the eiTor exists 
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12 Presence and Availability Management Exception 
Classes 

The following are the list of exception classes which are used in this interface of the API. 



Name 


Description 


P_PAM_AGENT_EXI STS 




ndicates that an Agent with the agentName already exists 


P_PAM_ALIAS_EXISTS 




ndicates that the specified alias is already associated to the Identity 


P_PAM_ALIAS_NOT_UNIQUE 




ndicates that the alias has already been assigned to another identity 


P_PAM_ATTRIBUTE_EXISTS 




ndicates that at least one of the named attributes already exists 


P_PAM_DISASSOCIATED_TYPE 




ndicates that one of the specified types is not associated with the named identity/agent 


P_PAM_IDENTITY_EXISTS 




ndicates that the specified Identity already exists 


P_PAM_INVALID_CREDENTIAL 




ndicates that the credential presented is not recognized or insufficient for the operation 


P_PAM_IS_CYCLIC 




ndicates that the requested operation will create cyclic relationship 


P_PAM_MEMBER_EXISTS 




ndicates that the specified member is already in the group 


P_PAM_NO_CAPAB I L I TY 




ndicates that a supplied capability is not a capabihty of the requested agent. No attributes are affected 


P_PAM_NOT_MEMBER 




ndicates that the specified member is not member of the group 


P_PAM_NOT_REGISTERED 




ndicates that the interface was not previously registered 


P_PAM_NOT_SUP PORTED 




mplementation dependent status that indicates that this method is not supported by the implementation 


P_PAM_TYPE_ASSOCIATED 




ndicates that a named type has already been associated with the identity/agent 


P_PAM_TYPE_EXISTS 




ndicates that the named type already exists 


P_PAM_UNAS S I GNED_AL I AS 




ndicates that the specified ahas was not an alias of the named identity 


P_PAM_UNAVAILABLE_INTERFACE 




ndicates that the specified interface does not exist or is unavailable 


P_PAM_lINKNOWN_AGENT 




ndicates that the Agent with the specified name does not exist 


P_PAM_UNKNOWN_ALIAS 




ndicates that the Alias with the specified name does not exist 


P_PAM_UNKNOWN_AS S I GNMENT 




ndicates that no assignment exists for this identity and agent 


P_PAM_UNKNOWN_ATTRIBUTE 




ndicates that at least one of the specified attributes has not been defined or has not been associated with 
he specified object 


P_PAM_UNKNOWN_ATTRIBUTES 


indicates that the specified attribute list contains attributes not part of the named object 


P_PAM_UNKNOWN_CAPAB I L I TY 


indicates that a supplied capability is not a capability of the requested agent, or has not been defined. No 
attributes are affected 


P_PAM_UNKNOWN_GROUP 


indicates that the specified group identity does not exist 


P_PAM_UNKNOWN_IDENTITY 


indicates that the specified identity does not exist 


P_PAM_UNKNOWN_MEMBER 


indicates that the specified member identity does not exist 


P_PAM_UNKNOWN_TYPE 


indicates that the named type does not exist / indicates that the named identity/agent has not been 
associated with the named type / indicates that a specified type name has not been defined as an agent 
type 



Each exception class contains the following structure. 



Structure Element Name 


Structure Element Type 


Structure Element Description 


Extrainf ormation 


TpString 


Carries extra information to help identify the source of the 
exception, e.g. a parameter name 
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Annex A (normative): 

OMG IDL Description of Presence and Availability 

Management SCF 

The OMG IDL representation of this interface specification is contained in text files (pam_interfaces, pam_data.idl) 
contained in archive 2919814V800IDL.ZIP which accompanies the present document. 
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Annex B (informative): 

W3C WSDL Description of the Presence and Availability 

Management SCFs 

The W3C WSDL representation of this interface specification is contained in zip file 2919814V800WSDL.ZIP, which 
accompanies the present document. 
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Annex C (informative): 

Java™ API Description of the Presence and Availability 

Management SCFs 

The JavaT*^ API realisation of this interface specification is produced in accordance with the JavaT"^ ReaHsation rules 
defined in Part 1 of this specification series. These rules aim to deliver for Java''^, a developer API, provided as a 
realisation, supporting a Java^*^ API that represents the UML specifications. The rules support the production of both 
J2SE''''^ and J2EE'"'^ versions of the API from the common UML specifications. 

The J2SET'^ representation of this interface specification is provided as Java'^*^ Code, contained in archive 
2919814V800J2SE.ZIP that accompanies the present document. 

The J2EE"^ representation of this interface specification is provided as Java'"^ Code, contained in archive 
2919814V800J2EE.ZIP that accompanies the present document. 
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Annex D (informative): 

Description of Presence and Availability Management for 

3GPP2 cdma2000 networks 

This annex is intended to define the OSA API Stage 3 interface definitions and it provides the complete OSA 
specifications. It is an extension of OSA API specifications capabilities to enable operation in cdma2000 systems 
environment. They are in alignment with 3GPP2 Stage 1 requirements and Stage 2 architecture defined in 

[1] 3GPP2 P.SOOOl-B: "Wireless IP Network Standard", Version 1.0, September 2000; 

[2] 3GPP2 S.R0037-0: "IP Network Architecture Model for cdma2000 Spread Spectrum Systems", 

Version 2.0, May 14, 2002; 

[3] 3GPP2 X.S0013: "All-IP Core Network Multimedia Domain", December 2003. 

These requirements are expressed as additions to and/or exclusions from the 3GPP Release 8 specification. 

The information given here is to be used by developers in 3GPP2 cdma2000 network architecture to interpret the 3GPP 

OSA specifications. 



D.1 General Exceptions 



The term UMTS is not applicable for the cdma2000 family of standards. Nevertheless these terms are used (3GPP TR 
21.905) mostly in the broader sense of "3G Wireless System". If not stated otherwise there are no additions or 
exclusions required. 

CAMEL and CAP mappings are not applicable for cdma2000 systems. 



D.2 Specific Exceptions 
D.2.1 Clause 1: Scope 

There are no additions or exclusions. 

D.2.2 Clause 2: References 

Normative references on 3GPP TS 23.078 and on 3GPP TS 29.078 are not applicable for cdma2000 systems. 

D.2. 3 Clause 3: Definitions and abbreviations 

There are no additions or exclusions. 

D.2. 4 Clause 4: Presence and Availability Management SCF 

There are no additions or exclusions. 

D.2. 5 Clause 5: Sequence Diagrams 

There are no additions or exclusions. 
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D.2.6 Clause 6 Class Diagrams 

There are no additions or exclusions. 

D.2.7 Clause 7: The Service Interface Specifications 

There are no additions or exclusions. 

D.2.8 Clause 8: Presence and Availability Management Interface 
Classes 

There are no additions or exclusions. 

D.2.9 Clause 9: State Transition Diagrams 

There are no additions or exclusions. 

D.2.10 Clause 10: PAM Service Properties 

There are no additions or exclusions. 

D.2.1 1 Clause 1 1 : PAM Data Definitions 

There are no additions or exclusions. 

D.2.1 2 Clause 12: Presence and Availability Management 
Exception Classes 

There are no additions or exclusions. 

D.2.1 3 Annex A (normative) :OMG IDL Description of Presence and 
Availability Management SCF 

There are no additions or exclusions. 

D.2.1 4 Annex C (informative): Java™ API Description of Presence 
and Availability Management SCF 

There are no additions or exclusions. 
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Annex E (informative): 
Change history 



Change history 


Date 


TSG# 


TSG Doc. 


CR 


Rev 


Subject/Comment 


Old 


New 


Mar 2007 


CT-35 


CP-070047 


0026 


-- 


Update document for conversion to Release 7 


6.3.1 


7.0.0 


May 2008 


CT-40 


CP-080254 


0027 


— 


Transfer of missing items from ETSI TISPAN OSA Presence and 
Availability Management specification. 


7.0.0 


8.0.0 


2009-12 


- 


- 


- 


- 


Update to Rel-9 version (MCC) 


8.0.0 


9.0.0 
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